Agent Orchestrator — The Orchestration Layer for Parallel AI Agents

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

---

Agent Orchestrator manages fleets of AI coding agents working in parallel on your codebase. Each agent gets its own git worktree, its own branch, and its own PR. When CI fails, the agent fixes it. When reviewers leave comments, the agent addresses them. You only get pulled in when human judgment is needed.

Agent-agnostic (Claude Code, Codex, Aider) · Runtime-agnostic (tmux, Docker) · Tracker-agnostic (GitHub, Linear)

See it in action

Quick Start

Option A — Install via npm (recommended):

npm install -g @composio/agent-orchestrator

# Permission denied? Use one of these:
sudo npm install -g @composio/agent-orchestrator   # quick fix
npx @composio/agent-orchestrator                    # no install needed

Prerequisites: Node.js 20+, Git 2.25+, tmux, gh CLI. Install tmux via brew install tmux (macOS) or sudo apt install tmux (Linux).

Option B — Install from source (for contributors):

git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator && bash scripts/setup.sh

Then set up your project:

# From a repo URL (fastest — clones, configures, and launches in one command)
ao start https://github.com/your-org/your-repo

# Or from an existing local repo
cd ~/your-project && ao init    # auto-detects everything, zero prompts
ao start

# Add more projects to an existing setup
ao add-project ~/path/to/another-repo

Spawn agents:

ao spawn my-project 123    # GitHub issue, Linear ticket, or ad-hoc

Dashboard opens at http://localhost:3000. Run ao status for the CLI view.

How It Works

ao spawn my-project 123

1. Workspace creates an isolated git worktree with a feature branch
2. Runtime starts a tmux session (or Docker container)
3. Agent launches Claude Code (or Codex, or Aider) with issue context
4. Agent works autonomously — reads code, writes tests, creates PR
5. Reactions auto-handle CI failures and review comments
6. Notifier pings you only when judgment is needed

Plugin Architecture

Eight slots. Every abstraction is swappable.

Slot	Default	Alternatives
Runtime	tmux	docker, k8s, process
Agent	claude-code	codex, aider, opencode
Workspace	worktree	clone
Tracker	github	linear
SCM	github	—
Notifier	desktop	slack, composio, webhook
Terminal	iterm2	web
Lifecycle	core	—

All interfaces defined in packages/core/src/types.ts. A plugin implements one interface and exports a PluginModule. That's it.

Configuration

# agent-orchestrator.yaml
port: 3000

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

projects:
  my-app:
    repo: owner/my-app
    path: ~/my-app
    defaultBranch: main
    sessionPrefix: app

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m
  approved-and-green:
    auto: false # flip to true for auto-merge
    action: notify

CI fails → agent gets the logs and fixes it. Reviewer requests changes → agent addresses them. PR approved with green CI → you get a notification to merge.

See agent-orchestrator.yaml.example for the full reference.

CLI

ao init                                # Auto-detect project and generate config
ao init --interactive                  # Full setup wizard with manual prompts
ao add-project <path>                  # Add another project to existing config
ao start [project]                     # Start dashboard + orchestrator
ao status                              # Overview of all sessions
ao spawn <project> [issue]             # Spawn an agent
ao send <session> "Fix the tests"      # Send instructions
ao session ls                          # List sessions
ao session kill <session>              # Kill a session
ao session restore <session>           # Revive a crashed agent
ao dashboard                           # Open web dashboard
ao doctor [--fix]                      # Check install, runtime, and stale temp issues
ao update                              # Update local AO install and run smoke tests

Maintenance

# Run deterministic install and runtime checks
ao doctor

# Apply safe cleanup and launcher fixes
ao doctor --fix

# Update this local AO checkout, rebuild critical packages, and verify the launcher
ao update

ao doctor checks PATH and launcher resolution, required binaries, tmux and GitHub CLI health, config support directories, stale AO temp files, and core build/runtime sanity. ao update fast-forwards the local install repo on main, runs pnpm install, clean-rebuilds @composio/ao-core, @composio/ao-cli, and @composio/ao-web, refreshes the global ao launcher with npm link, and finishes with CLI smoke tests.

Why Agent Orchestrator?

Running one AI agent in a terminal is easy. Running 30 across different issues, branches, and PRs is a coordination problem.

Without orchestration, you manually: create branches, start agents, check if they're stuck, read CI failures, forward review comments, track which PRs are ready to merge, clean up when done.

With Agent Orchestrator, you: ao spawn and walk away. The system handles isolation, feedback routing, and status tracking. You review PRs and make decisions — the rest is automated.

Prerequisites

• Node.js 20+
• Git 2.25+
• tmux (for default runtime)
• gh CLI (for GitHub integration)

Development

pnpm install && pnpm build    # Install and build all packages
pnpm test                      # Run tests (3,288 test cases)
pnpm dev                       # Start web dashboard dev server

See docs/DEVELOPMENT.md for code conventions and architecture details.

Documentation

Doc	What it covers
Setup Guide	Detailed installation and configuration
Examples	Config templates (GitHub, Linear, multi-project, auto-merge)
Development Guide	Architecture, conventions, plugin pattern
Contributing	How to contribute, build plugins, PR process
Troubleshooting	Common issues and fixes

Contributing

Contributions welcome. The plugin system makes it straightforward to add support for new agents, runtimes, trackers, and notification channels. Every plugin is an implementation of a TypeScript interface — see CONTRIBUTING.md and the Development Guide for the pattern.

License

MIT