Introduction
Learn what Agent Orchestrator does, when to use it, and where to start.
Agent Orchestrator (AO) runs AI coding agents in isolated git worktrees and keeps track of the work until it becomes a pull request.
Use it when you have several well-scoped issues and want agents to work on them at the same time without sharing a checkout, terminal, or branch. AO starts each session, watches the agent, tracks the PR, and shows the state of every session in one dashboard.
Fastest path
If you are new to AO, install it first, then run the quickstart against one small issue. Start with Installation, then Quickstart.
What AO Is For
AO is useful when you want to:
- Run more than one coding agent at the same time.
- Keep every agent in its own worktree, branch, and session.
- Watch agent terminals and PR state from one dashboard.
- Let AO wake an agent when CI fails or a review requests changes.
- Use different agent CLIs across projects or roles, such as Claude Code, Codex, Cursor, Aider, and OpenCode.
AO works best for issues that have a clear outcome: failing tests, small features, focused refactors, migrations, documentation updates, and review follow-ups.
What AO Does Not Do
AO does not replace review. It helps agents keep working, but you still decide what gets merged.
| AO handles | You still handle |
|---|---|
| Creating isolated workspaces | Choosing good issues |
| Launching and monitoring agents | Reviewing code and behavior |
| Tracking PR, CI, and review status | Deciding when to merge |
| Cleaning up merged sessions | Setting repo-specific rules and expectations |
How A Session Moves
issue -> ao spawn -> worktree + agent -> pull request -> CI/review loop -> merge -> cleanupThe dashboard shows this lifecycle as session cards. Open a card to see the live terminal, current activity state, issue link, PR link, and worktree path.
How AO Fits Together
AO is built from plugins. The default setup works out of the box for common GitHub workflows, and you can swap pieces when your setup is different.
| Plugin slot | What it controls | Examples |
|---|---|---|
| Agent | Which coding tool writes changes | Claude Code, Codex, Cursor, Aider, OpenCode |
| Runtime | How the agent process runs | tmux, child process |
| Workspace | Where code is checked out | git worktree, full clone |
| Tracker | Where issues come from | GitHub, GitLab, Linear |
| SCM | How PRs, reviews, and CI are read | GitHub, GitLab |
| Notifier | Where AO sends updates | desktop, Slack, Discord, webhook |
Most users start with the defaults and only edit agent-orchestrator.yaml when they need a different agent, runtime, tracker, or notification target.
Platform Support
Windows support is actively improving. Use the process runtime instead of tmux by setting defaults.runtime: process in agent-orchestrator.yaml. See Platforms for details.
Where To Go Next
Installation
Install AO, authenticate your tools, and run the doctor check.
Quickstart
Spawn one agent on one issue and watch it open a PR.
Configuration
Understand the `agent-orchestrator.yaml` file.
Guides
Run parallel issues, recover from CI failures, and handle review loops.
Plugins
See which agents, runtimes, trackers, SCMs, terminals, and notifiers are available.
Troubleshooting
Fix common install, dashboard, runtime, and session problems.