@aoagents/ao

Agent Orchestrator (ao)

The orchestration layer for parallel AI coding agents.

Spawn parallel AI coding agents, each in its own git worktree, on a single machine. Agents autonomously fix CI failures, address review comments, and open PRs — you supervise the whole fleet from one dashboard.

Agent-agnostic (Claude Code, Codex, Aider, Cursor, OpenCode) · Runtime-agnostic (tmux, ConPTY/process, Docker) · Tracker-agnostic (GitHub, Linear, GitLab)

Install

npm install -g @aoagents/ao

Nightly builds (latest main): npm install -g @aoagents/ao@nightly — back to stable with @latest.

Prerequisites: Node.js 20.18.3+, Git 2.25+, the gh CLI, and at least one coding-agent CLI (e.g. Claude Code).

• macOS / Linux: tmux — brew install tmux or sudo apt install tmux.
• Windows: PowerShell 7+ recommended; tmux is not required (AO uses native ConPTY via the process runtime).

Quick start

Point it at any repo — it clones, configures, and launches the dashboard in one command:

ao start https://github.com/your-org/your-repo

Or from inside an existing local repo:

cd ~/your-project && ao start

The dashboard opens at http://localhost:3000 and an orchestrator agent starts managing your project. Add more repos any time:

ao start ~/path/to/another-repo

You don't need to learn the CLI — the dashboard and the orchestrator agent drive everything. (Individual ao commands are documented in the CLI Reference and used internally by the orchestrator.)

How it works

• You start — ao start launches the dashboard and an orchestrator agent.
• Orchestrator spawns workers — each issue gets its own agent in an isolated git worktree and branch.
• Agents work autonomously — they read code, write tests, and open PRs.
• Reactions handle feedback — CI failures and review comments are routed back to the responsible agent automatically.
• You review and merge — you're pulled in only when human judgment is needed.

Pluggable by design

Seven plugin slots; the lifecycle state machine stays in core:

Slot	Default	Alternatives
Runtime	tmux (macOS/Linux) / process (Windows)	process, docker
Agent	claude-code	codex, aider, cursor, opencode, kimicode
Workspace	worktree	clone
Tracker	github	linear, gitlab
SCM	github	gitlab
Notifier	desktop	slack, discord, composio, webhook, openclaw
Terminal	iterm2	web

Why Agent Orchestrator?

Running one AI agent in a terminal is easy. Running 30 across different issues, branches, and PRs is a coordination problem: creating branches, detecting stuck agents, reading CI failures, forwarding review comments, tracking which PRs are ready, and cleaning up afterward.

Agent Orchestrator handles the isolation, feedback routing, and status tracking. You ao start and walk away — then review PRs and make decisions. The rest is automated.

Documentation

• 📖 Project README & overview
• 🛠️ Setup guide — install, configuration, troubleshooting
• ⌨️ CLI reference
• 🧩 Development & plugin guide
• 💬 Discord community

License

MIT © ComposioHQ