Installation
Install AO, authenticate the tools it controls, and verify your first project.
This page gets your machine ready to run Agent Orchestrator. By the end, the ao command should be on your PATH, your source-control CLI should be authenticated, and ao doctor should be able to explain what is ready or missing.
What AO installs
The published package is @aoagents/ao. It provides the global ao command and includes the built-in CLI, dashboard, and plugin packages.
Prerequisites
Windows support is actively improving. Use defaults.runtime: process instead of tmux. See Platforms.
Install these before running AO:
| Tool | Required | Why AO needs it |
|---|---|---|
| Node.js 20+ | Yes | Runs the AO CLI, dashboard, and plugins. |
| Git | Yes | Creates worktrees, branches, commits, and cleanup operations. |
GitHub CLI gh | For GitHub projects | Reads issues, PRs, reviews, and CI status as your user. |
| tmux | Default on macOS/Linux | Keeps long-running agent sessions attachable and recoverable. |
| An agent CLI | Yes | The worker that writes code, such as Claude Code, Codex, Cursor, Aider, or OpenCode. |
If you plan to use GitLab or Linear, install and authenticate their CLIs or credentials as described on the related plugin pages. A GitHub-only setup only needs gh.
Install AO
npm install -g @aoagents/aopnpm add -g @aoagents/aoyarn global add @aoagents/aogit clone https://github.com/ComposioHQ/agent-orchestrator
cd agent-orchestrator
pnpm install
pnpm build
pnpm --filter @aoagents/ao link --globalConfirm the command is available:
ao --versionAuthenticate Your Tools
Authenticate source control
For GitHub projects, AO uses gh for issue lookup, PR discovery, reviews, CI checks, and merge readiness.
gh auth login
gh auth statusThe authenticated account must be able to read the repository, create branches, push branches, open PRs, and read CI status.
Install and sign in to one agent
AO launches an agent CLI inside each worker session. Start with the one you already use, then add more later if you want per-project or per-role choices.
npm install -g @anthropic-ai/claude-code
claudenpm install -g @openai/codex
codexcurl https://cursor.com/install -fsS | bash
agent --helppip install aider-install
aider-install
aider --helpnpm install -g opencode-ai
opencode --helpStart AO in a repo
Run ao start from a repository you want AO to manage:
cd ~/code/my-repo
ao startIf there is no agent-orchestrator.yaml, AO creates one. It also starts the dashboard and an orchestrator session for the project.
You can also start from a path or clone from a URL:
ao start ~/code/my-repo
ao start https://github.com/your-org/your-repoRun the doctor check
ao doctorao doctor checks the launcher, config, plugin resolution, runtime tools, source-control authentication, notifier setup, and stale temporary files. If it reports a fixable issue, run:
ao doctor --fixWindows Setup
Windows support is in progress. Use the process runtime instead of tmux:
defaults:
runtime: processUse Slack, Discord, webhook, or another network notifier for alerts. Desktop notifications and iTerm2 integration are not available on Windows.