First step: ao doctor
ao doctor
ao doctor --fix # auto-repair safe things
ao doctor --test-notify # send a test through each notifier
Covers: install health, plugin resolution, notifier connectivity, stale temp files.
Install & environment
`ao: command not found`
The npm global bin isn't on your PATH. Find it with npm config get prefix and add <prefix>/bin to your shell's PATH.
`tmux: command not found` (on Windows)
Expected. Use runtime: process in your config. See Platforms.
`gh: authentication required`
Run gh auth login. AO uses gh for every GitHub interaction.
Port 3000 already in use
AO auto-picks the next free port. You'll see the actual URL in the ao start output.
Dashboard crashes with 'vendor-chunks not found'
Stale Next.js artifacts. Run ao dashboard --rebuild.
Agents & sessions
`ao spawn` hangs at 'waiting for idle'
The agent never reached idle state. Run ao status --watch to see what's happening — if it's legitimately working (e.g. large install step), wait. Otherwise ao session kill <session> and spawn again.
Dashboard activity stuck on 'active' or 'idle'
getActivityState reads the agent's JSONL / activity log. If that file is missing or stale, you'll see wrong states. ao doctor flags this. See the agent's individual plugin page under Plugins › Agents for recovery.
Agent opened a PR but the dashboard doesn't know
The PATH wrapper didn't record it (possible if the agent called gh by absolute path). Use ao session claim-pr <pr> <sessionId> to link retroactively.
Session won't restore
ao session restore <sessionId> relaunches the agent in the same worktree. If restore keeps failing, check the agent plugin's resume docs — some agents don't support resume at all (Cursor, Aider).
`Session can't be found` with OpenCode
Run ao session remap <sessionId> to re-discover the OpenCode mapping. Use --force if a stale mapping is stuck.
GitHub / SCM
GitHub API rate limit
AO paces calls, but heavy projects can still hit limits. The lifecycle manager backs off automatically. If you see
sustained rate-limit errors, check that you're logged in as yourself (gh auth status) — unauthenticated calls have
much lower limits.
CI recovery never fires
reactions.ciFailed.enabled: false in your config, or the PR is in draft. See CI recovery › When it doesn't kick
in.
Review loop never fires
Review feedback is only replayed on CHANGES_REQUESTED — not on plain COMMENTED reviews. See Review
loop.
Webhook delivers but nothing happens
HMAC signature check failing. Verify your secretEnvVar is exported and matches the secret you set on GitHub.
Notifications
Desktop notifications silent on macOS
System Settings → Notifications → allow your terminal app.
Desktop notifier warning on Windows
Expected. Add Discord, Slack, or a webhook notifier in the same notifier: list.
Slack webhook 429s under load
The slack notifier doesn't honor Retry-After. Use the generic webhook notifier
with retries tuned up.
Windows-specific
`ao open` prints a URL instead of opening a tab
Expected on Windows. The iTerm2 helper only runs on macOS. Use the dashboard's built-in terminal (the printed URL takes you there).
Child process exits immediately
Shell quoting issue. Pass long prompts via --prompt with simple ASCII, or via ao send --file <path>.
Still stuck
-
Check the FAQ.
-
Open an issue:
AgentWrapper/agent-orchestrator. When opening an issue, include: -
Output of
ao --version -
The contents of
~/.agent-orchestrator/{hash}-observability/processes/(one JSON snapshot per process; each contains traces, health, and metrics) -
Your
agent-orchestrator.yaml(redact any secrets)