Skip to main content

​
Introduction to Agent Orchestrator

Agent Orchestrator is an open-source system that manages fleets of AI coding agents working in parallel on your codebase. Each agent gets its own isolated workspace, branch, and PR—autonomously fixing CI failures, addressing review comments, and opening pull requests while you supervise from a unified dashboard.

​
What Problem Does It Solve?

Running a single AI agent in a terminal is straightforward. Running 30 agents across different issues, branches, and PRs becomes a coordination nightmare. Without orchestration, you manually:
  • Create branches for each task
  • Start agents in separate terminals
  • Monitor if they’re stuck or finished
  • Forward CI failures back to agents
  • Route review comments to the right agent
  • Track which PRs are ready to merge
  • Clean up workspaces when done
With Agent Orchestrator, you:
  • Run ao spawn and walk away
  • Get notified only when human judgment is needed
  • Let the system handle isolation, feedback routing, and lifecycle management
The orchestrator operates on a push, not pull principle—agents work autonomously and push notifications to you when decisions are required.

​
Key Concepts

​
Sessions

A session is an isolated workspace where one agent works on one task. Each session includes:
  • Its own git worktree or repository clone
  • Its own runtime environment (tmux session, Docker container, etc.)
  • Its own metadata tracking (branch, PR, status, events)
  • Its own lifecycle from spawn to merge
Sessions are ephemeral—created for a specific issue and destroyed after merging.

​
Plugin Architecture

Agent Orchestrator uses 8 pluggable slots. Every abstraction is swappable:
SlotPurposeDefaultAlternatives
RuntimeHow sessions executetmuxprocess, docker, kubernetes, ssh, e2b
AgentAI coding assistantclaude-codecodex, aider, goose, custom
WorkspaceCode isolation methodworktreeclone, copy
TrackerIssue trackinggithublinear, jira, custom
SCMSource control platformgithubGitLab, Bitbucket (coming soon)
NotifierPush notificationsdesktopslack, discord, webhook, email
TerminalUI integrationiterm2web, custom
LifecycleSession management(core)Non-pluggable
All plugin interfaces are defined in packages/core/src/types.ts. A plugin implements one interface and exports a PluginModule—that’s it.

​
Reactions

Reactions are automated responses to common events. The orchestrator can handle routine scenarios without human intervention: 
reactions:
  ci-failed:
    auto: true              # Enable auto-handling
    action: send-to-agent   # Forward CI logs to agent
    retries: 2              # Allow 2 retry attempts
    escalateAfter: 2        # Notify human after 2 failures
When auto: true, the orchestrator handles the event automatically. When escalation thresholds are reached, you get notified.

​
Workspaces: Worktree vs Clone

Worktree (default):
  • Shares .git directory with main repository
  • Fast to create (no cloning required)
  • Efficient disk usage
  • Best for local development
Clone:
  • Full independent repository clone
  • Slower to create
  • More disk space required
  • Better for complete isolation or remote work

​
How It Works

When you run: 
ao spawn my-project 123
The orchestrator executes this workflow:
1

Create Workspace

Creates an isolated git worktree (or clone) with a feature branch
2

Start Runtime

Launches a tmux session (or Docker container, etc.) for the agent
3

Spawn Agent

Starts the AI agent (Claude Code, Codex, Aider) with issue context
4

Autonomous Work

Agent reads code, writes tests, commits changes, and creates a PR
5

Automatic Reactions

System auto-handles CI failures and review comments via reactions
6

Human Notification

You receive a notification only when your judgment is needed

​
Architecture Overview

Agent Orchestrator is built as a TypeScript monorepo using pnpm workspaces: 
packages/
  core/          — @composio/ao-core (types, config, core services)
  cli/           — @composio/ao-cli (the `ao` command)
  web/           — @composio/ao-web (Next.js dashboard)
  plugins/
    runtime-*/    — Runtime plugins (tmux, process, docker)
    agent-*/      — Agent plugins (claude-code, codex, aider)
    workspace-*/  — Workspace plugins (worktree, clone)
    tracker-*/    — Tracker plugins (github, linear)
    scm-*/        — SCM plugins (github PR/CI/review)
    notifier-*/   — Notifier plugins (desktop, slack, webhook)
    terminal-*/   — Terminal plugins (iterm2, web)
packages/ core/ — @composio/ao-core (types, config, core services) cli/ — @composio/ao-cli (the ao command) web/ — @composio/ao-web (Next.js dashboard) plugins/ runtime-/ — Runtime plugins (tmux, process, docker) agent-/ — Agent plugins (claude-code, codex, aider) workspace-/ — Workspace plugins (worktree, clone) tracker-/ — Tracker plugins (github, linear) notifier-/ — Notifier plugins (desktop, slack, webhook) scm-/ — SCM plugins (github) terminal-*/ — Terminal plugins (iterm2, web) 

<Info>
All plugin interfaces are defined in a single source of truth: `packages/core/src/types.ts`. Read this file first when developing custom plugins.
</Info>

## Design Principles

1. **Agent-agnostic**: Works with any AI coding tool (Claude Code, Codex, Aider, custom)
2. **Runtime-agnostic**: Run in tmux, Docker, Kubernetes, or cloud sandboxes
3. **Tracker-agnostic**: Integrates with GitHub, Linear, Jira, or custom systems
4. **Push notifications**: You get notified—don't poll for status
5. **Stateless orchestrator**: No database required, uses flat metadata files
6. **Security first**: All shell commands use `execFile` (not `exec`), input validation on all external data

## When to Use Agent Orchestrator

Agent Orchestrator is ideal when you need to:

- Run multiple AI agents in parallel on different issues
- Automatically retry failed CI builds
- Route review comments back to the agent that created the PR
- Track agent progress across many concurrent tasks
- Isolate agent work in separate git branches/worktrees
- Centralize monitoring and control from one dashboard

<Note>
If you only need to run one agent at a time in a single terminal, you may not need orchestration. Agent Orchestrator shines when coordinating multiple concurrent agent sessions.
</Note>

## What Makes It Different?

Unlike single-agent coding tools, Agent Orchestrator provides:

- **Parallel execution**: Run 30 agents simultaneously on 30 different issues
- **Lifecycle management**: Automatic session creation, monitoring, and cleanup
- **Event-driven reactions**: Auto-handle CI failures and review comments
- **Unified supervision**: One dashboard to monitor all active sessions
- **Flexible architecture**: Swap any component via the plugin system

## Next Steps

Ready to get started? Follow the quickstart guide to spawn your first agent:

<Card title="Quickstart" icon="rocket" href="/quickstart">
  Get Agent Orchestrator running in 5 minutes
</Card>

Or dive into detailed installation instructions:

<Card title="Installation" icon="download" href="/installation">
  Complete setup guide with prerequisites and configuration
</Card>

Build docs developers (and LLMs) love

Get started for freeTalk to us