Docs

Gotchas

The trust gates and approval quirks that make setup fail silently — and the fixes.

Most of these fail silently — the setup looks fine and then quietly does nothing. They’re worth knowing before you conclude “it doesn’t work.”

Both agents gate on workspace trust

uac init writes config, but each agent ignores it until you trust the project.

• Claude Code drops its permission rule (“this workspace has not been trusted”) and then silently refuses every memory_write, quietly falling back to its own private memory — the exact split-brain uac exists to prevent.
• Codex refuses to run at all (“Not inside a trusted directory”).

Fix: run each CLI in the project once and accept the trust prompt.

Codex needs its hooks trusted, too

Even after directory trust, Codex ignores wrapper-installed hooks until you approve them. Skip this and the session-start hook never runs — so Codex is never told the shared memory exists, and when you ask it a question it greps the filesystem and reports it found nothing.

Fix: inside codex, run /hooks and trust the uac hooks. (Upstream: openai/codex#21615.)

Headless Codex can read memory, but not write it

codex exec (non-interactive) auto-cancels MCP tool calls unless the tool is advertised read-only (#16685). uac annotates its read tools readOnlyHint, so memory_search, skill_load, skill_list and project_context work headlessly. memory_write and memory_forget are honestly not read-only, so they’re cancelled in headless Codex — they work in an interactive session, where you approve them.

We annotate honestly rather than mislabel a write to slip it past the gate.

Claude’s Auto Memory can double-write

Claude ships built-in Auto Memory. Running it alongside uac’s Stop nudge can produce two summaries. Set claude_auto_memory = "native" in config to leave Claude’s side to its own memory.

The MCP permission gate (handled, but worth knowing)

permissions.allow in .claude/settings.json is ignored until the workspace is trusted, so the front ends pass --allowed-tools mcp__uac on the command line — which works regardless of trust. If you script claude yourself, do the same.

Node version, for the docs site and extension packaging

Some Node tooling (this docs site, vsce) needs Node ≥ 18.20.8 / 20 / 22. Older 18.x refuses to build. Install a newer Node (system or user-local) if you hit it.