Quickstart
Start AO, spawn one worker session, and follow it from task to pull request.
This quickstart walks through the smallest useful AO loop: start the dashboard, create one worker session, watch it work, and clean it up after the PR is merged.
Before you start
Complete Installation first. You need ao, Git, one authenticated source-control CLI such as gh, and one signed-in agent CLI.
Pick A Safe First Task
Use a repository where you can push a branch and open a pull request. For the first run, choose a task that is easy to review:
- Fix a small bug with a clear failure.
- Update a short documentation page.
- Add a narrow test.
- Make a small refactor with obvious acceptance criteria.
Avoid broad tasks like “improve auth” or “clean up the app.” AO can run many agents, but each worker still needs a task with a visible finish line.
Run The First Session
Start AO
From the repository you want AO to manage:
cd ~/code/my-repo
ao startOn the first run, AO creates agent-orchestrator.yaml, starts the dashboard, and starts an orchestrator session for the project. The dashboard URL is printed in the terminal, usually http://localhost:3000.
Keep this terminal running. It owns the dashboard and lifecycle polling.
Spawn one worker
Open a second terminal in the same repository.
ao spawn 42Replace 42 with the issue number. AO fetches the issue through gh, creates a worktree, starts the configured worker agent, and gives it the issue context.
ao spawn --prompt "Update the README install section to mention Node 20"Use this when the task is not tracked in GitHub, GitLab, or Linear yet. Keep the prompt specific and reviewable.
The command prints the session id and dashboard URL. Session names use the project prefix, for example myrepo-1.
Watch the dashboard
Open the session card. You should see:
- The worker activity state: active, ready, idle, waiting for input, blocked, or exited.
- The worktree path and branch name.
- The live terminal output.
- The PR link after the agent creates one.
- CI and review state after a PR exists.
Use ao status when you want the same high-level view in a terminal:
ao statusIntervene only when needed
AO routes routine feedback back to the worker:
- CI failure: AO sends failure context to the session.
- Requested changes: AO sends the review feedback to the session.
- Merge conflicts: AO can ask the worker to rebase or resolve the conflict.
- Agent stuck or waiting for input: AO notifies you.
If you need to give the worker a direct instruction, use ao send:
ao send myrepo-1 "Keep the fix smaller. Do not refactor the API layer."Use ao send instead of raw terminal input. It preserves AO's busy detection, retry handling, and message formatting.
Review and merge
When the PR is green and ready, review it like any other pull request. AO does not merge by default.
After the PR is merged or the issue is closed, clean up completed sessions:
ao session cleanup --dry-run
ao session cleanupWhat AO Created
| Item | What it means |
|---|---|
agent-orchestrator.yaml | Project config: plugins, projects, reactions, runtime, and notifier choices. |
| Orchestrator session | A coordinating session started by ao start; it supervises worker sessions. |
| Worker session | The agent process that works on one issue or prompt. |
| Worktree | An isolated checkout for the worker's branch. |
| Session metadata | Files under ~/.agent-orchestrator/... that let AO track branch, PR, status, and runtime state. |
If Something Looks Wrong
| Symptom | First check |
|---|---|
| Dashboard is not updating | Make sure the ao start terminal is still running. |
ao spawn warns that AO is not running | Start AO with ao start before spawning. |
| GitHub issue or PR data is missing | Run gh auth status and check the repo field in agent-orchestrator.yaml. |
| Agent started but does nothing | Open the session terminal and send a clear instruction with ao send. |
| Windows spawn fails with tmux errors | Set defaults.runtime: process in agent-orchestrator.yaml. |