Unpacked: Agent Orchestrator (AO)

What It Is

Agent Orchestrator (AO) is an open-source tool by ComposioHQ that runs up to 30 coding agents in parallel, each in its own isolated git worktree. You point it at GitHub issues, it spawns agents (Claude Code, Codex, Aider, or others), and each one creates a branch, writes code, opens a PR, and handles CI failures and review comments autonomously. You supervise from a single web dashboard. MIT licensed, 6.3K stars on GitHub.

Get It Running

Prerequisites: Node.js 20.18.3+, Git 2.25+, and gh CLI authenticated. On macOS/Linux you also need tmux.

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Install AO globally
npm install -g @aoagents/ao

# Navigate to your project and start
cd ~/your-project
ao start

That’s it. ao start launches the orchestrator agent and opens a web dashboard at localhost:3000. The orchestrator reads your GitHub issues, decomposes them into tasks, and spawns worker agents.

If you want to try it without a global install:

npx @aoagents/ao start

Your First Multi-Agent Run

Once the dashboard is up, AO picks issues from your repo’s backlog. You control it with an agent-orchestrator.yaml at the project root. Here’s a minimal config:

$schema: https://raw.githubusercontent.com/ComposioHQ/agent-orchestrator/main/schema/config.schema.json
port: 3000

defaults:
	agent: claude-code
	runtime: tmux
	workspace: worktree
	notifiers: [desktop]

projects:
	my-app:
		repo: org/my-app
		path: ~/my-app
		defaultBranch: main

Picking Your Agents

You can split the orchestrator (the agent that decomposes issues into tasks) from the workers (the agents that write code). This lets you use a stronger model for planning and a cheaper one for execution:

defaults:
	orchestrator:
		agent: claude-code
	worker:
		agent: codex

# Or override per project:
projects:
	my-app:
		worker:
			agent: aider
		agentConfig:
			model: "claude-sonnet-4-20250514"

Available agents: claude-code, codex, aider, cursor, opencode, kimicode.

Reactions: Automated CI and Review Handling

The reactions block is the part that saves you time. When CI fails on a PR, AO routes the failure back to the agent that created it. Same for review comments. You can also detect stuck agents and get notified when a PR is approved and green:

reactions:
	ci-failed:
		auto: true
		action: send-to-agent
		retries: 2
		escalateAfter: 2
	changes-requested:
		auto: true
		action: send-to-agent
		escalateAfter: 30m
	approved-and-green:
		auto: false
		action: notify
		priority: action
	agent-stuck:
		threshold: 10m
		action: notify
		priority: urgent

Other Useful Settings

power:
	preventIdleSleep: true            # keeps macOS awake while agents run

lifecycle:
	autoCleanupOnMerge: true          # deletes worktrees after PR merge
	mergeCleanupIdleGraceMs: 300000   # 5 min grace period before cleanup

observability:
	logLevel: warn                    # debug | info | warn | error

Run ao config-help for the full schema reference.

What Worked, What Didn’t

• Setup takes about 2 minutes. ao start and you’re watching agents work. No config file required for the basic case.
• Worktree isolation is the right call. Each agent gets its own branch and working copy, so they can’t step on each other’s files. autoCleanupOnMerge keeps disk usage in check.
• The orchestrator/worker split is smart. Use a stronger model to plan (Claude Code) and a cheaper one to execute (Codex or Aider). Cuts cost without losing task quality.
• Agents don’t talk to each other. Two agents can end up solving overlapping problems differently. On a small team this is manageable, on a monorepo with shared modules it’s a real risk.
• No built-in cost cap. There’s no maxTokens or budget field in the config. 10 parallel agents means 10x the token bill. Set spending limits at the API provider level before you run this on a large backlog.

When to Use This

Use AO when you have a backlog of independent issues (bug fixes, small features, test coverage) and want to parallelize the work across agents. Skip it if your tasks have heavy interdependencies or you need agents to coordinate on shared code.