Quickstart

Pick a repo and an issue

Pick a GitHub repo you own and an open issue that has a clear, self-contained fix. Something small — a typo, a failing test, a small refactor. The goal is to see the loop work end-to-end, not to stress-test the agent.

Note the issue number. We'll use 42 below.

Start AO

cd ~/projects/my-repo
ao start

On first run with no config, AO auto-generates agent-orchestrator.yaml and opens the dashboard at http://localhost:3000.

If the dashboard doesn't open automatically, copy the URL from the ao start output.

Spawn an agent

In a second terminal, from the same directory:

ao spawn 42

AO will:

1. Look up issue #42 via gh
2. Create an isolated worktree under ~/.agent-orchestrator/...
3. Launch your default agent in it with a prompt built from the issue

The dashboard card moves through Spawning → Working within a few seconds.

Watch it work

Open the session on the dashboard to see:

• A live terminal (xterm.js + WebSocket) showing what the agent is doing
• The current activity state (active / ready / idle / waiting_input)
• Issue link, worktree path, session id

When the agent pushes a commit and opens a PR, the card moves to PR Open. AO picks up the PR via the gh CLI — no webhook setup needed.

Let the loop run

• CI fails? AO notices and wakes the agent to investigate and push a fix.
• Review requested changes? AO spots the REQUEST_CHANGES review and nudges the agent with the review body.
• CI green, no reviewers blocking? Card moves to Mergeable.

You merge when you're ready — AO doesn't auto-merge (on purpose).

Clean up

After the PR merges:

ao session cleanup

Removes worktrees whose PR merged or whose issue closed. Nothing is destructive — archived metadata stays under ~/.agent-orchestrator/.../archive/.