Gotchas while using AO

[harshitsinghbhandari]

A running list of non-obvious gotchas hit while using AO (the ao daemon + CLI + spawned agent workers), with the root cause and the fix for each. Reply with your own and I'll fold them in.

---

1. Spawned workers come up Not logged in when the daemon was started from inside a Claude Code session

Symptom

A worker spawned with ao spawn ... --agent claude-code (the default agent) boots into its zellij pane but the Claude Code TUI shows:

Not logged in  Please run /login
IDE extension install failed (see /status for info)

The task never starts because the agent has no auth, even though running claude yourself in a normal terminal works fine.

Root cause

Auth flows from the daemon's environment down to every worker:

1. Your interactive shell has CLAUDE_CODE_OAUTH_TOKEN exported, which is why a claude you launch yourself is authenticated.
2. Claude Code strips CLAUDE_CODE_OAUTH_TOKEN (and similar secrets) from the environment it hands to its own Bash tool, for security. So the token is invisible to anything Claude Code runs as a subprocess.
3. If you let Claude Code run ao start for you, the daemon inherits that scrubbed, tokenless environment.
4. The zellij runtime spawns every worker with the daemon's os.Environ() (backend/internal/adapters/runtime/zellij/zellij.go), so each worker inherits the tokenless env and comes up logged out.

It is not a build, daemon, or AO bug. The daemon simply cannot pass along a token it never received.

How to confirm it:

# token is hidden from a Claude-Code-spawned shell:
printenv CLAUDE_CODE_OAUTH_TOKEN >/dev/null && echo present || echo "MISSING (scrubbed)"

# and it is absent from the running daemon's environment:
ps eww -p "$(pgrep -f 'ao daemon')" | tr ' ' '\n' | grep CLAUDE_CODE_OAUTH_TOKEN || echo "not in daemon env"

Fix

Always start the daemon from your own terminal, where the token is exported. Do not let Claude Code start it for you (a ! ao start typed into the Claude Code prompt is also run through the scrubbed shell, so that does not work either).

ao stop                                  # if a tokenless daemon is already running

# in your own terminal:
printenv CLAUDE_CODE_OAUTH_TOKEN >/dev/null && echo "token present" || echo "export it first"
ao start

Once the daemon holds the token, spawn / kill / status can be driven from anywhere, including from inside a Claude Code session, because the CLI is a thin client and the daemon (not the CLI) is what spawns workers and supplies their environment.

The same applies to the API-key path: if you authenticate workers with ANTHROPIC_API_KEY instead of OAuth, that variable must be present in the daemon's environment at ao start time, so export it in the terminal you start the daemon from.