ao-starter

Agent Orchestrator (ao) runs parallel Claude Code agents in isolated git worktrees, each on its own branch. When an agent opens a PR, ao watches CI and review events and routes failures back to the agent automatically. One operator can manage a fleet of agents across multiple issues at once without babysitting any of them.

Prerequisites

• macOS
• Homebrew
• tmux
• gh CLI authenticated (gh auth login)
• Node.js 18+ (for the ao npm package)
• Claude Code — agents run Claude Code, which requires a Claude Pro subscription or API access

Install

npm install -g @aoagents/ao

Or run the included setup script, which checks and installs all prerequisites:

./setup.sh

After install, verify everything is wired up:

ao doctor

Register your first project

Your project must be a git repo with a GitHub remote already configured.

./scripts/ao-register-project.sh /path/to/your/repo

The script handles the full registration lifecycle: creates an agent-orchestrator.yaml in your project root, registers the project with ao, purges any stale worktrees, and restarts ao so it picks up the new project.

Run it once per repo.

Start ao

ao start          # starts the dashboard and the orchestrator

The dashboard runs at http://localhost:3000.

Quick reference

Command	What it does
ao spawn --prompt "your task"	Spawn an agent with an inline prompt (4096 char max)
ao spawn <issue-number>	Spawn an agent against a GitHub issue
ao batch-spawn 101 102 103	Spawn agents for multiple issues at once
ao status	Snapshot of all sessions (branch, PR, CI, activity)
ao status --watch	Live-updating terminal view
ao session ls	List sessions with state
ao send <session-id> "message"	Send a follow-up to a running agent
ao open <session-id>	Attach to a session's tmux window
ao stop	Stop everything (dashboard, orchestrator, all sessions)
ao doctor	Check prerequisites and config health
ao doctor --fix	Apply safe fixes automatically

Add ao awareness to Claude

Drop the included CLAUDE.md into your Claude config so Claude knows how ao works and defaults to spawning agents for implementation work instead of doing it inline.

Option 1: Append to your global Claude config

cat CLAUDE.md >> ~/.claude/CLAUDE.md

Option 2: Add to a specific project

Copy CLAUDE.md to your project root. Claude Code picks it up automatically when working in that directory.

Verify everything works

ao doctor

Expected output: all checks green. If anything is red, ao doctor --fix resolves most issues automatically. The most common failure is gh not authenticated — run gh auth login to fix it, then re-run ao doctor.

Spawning tips

• Keep inline prompts under 4096 characters. For longer context, write a spec file and tell the agent to read it: ao spawn --prompt "Read /tmp/my-spec.md and implement it."
• ao spawn <issue-number> reads the full GitHub issue body automatically — no need to paste it in.
• Watch agents live: ao status --watch in one terminal, ao open <session-id> in another.