Introduction

Learn about Agent Orchestrator, the orchestration layer for parallel AI coding agents

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:

Slot	Purpose	Default	Alternatives
Runtime	How sessions execute	tmux	process, docker, kubernetes, ssh, e2b
Agent	AI coding assistant	claude-code	codex, aider, goose, custom
Workspace	Code isolation method	worktree	clone, copy
Tracker	Issue tracking	github	linear, jira, custom
SCM	Source control platform	github	GitLab, Bitbucket (coming soon)
Notifier	Push notifications	desktop	slack, discord, webhook, email
Terminal	UI integration	iterm2	web, custom
Lifecycle	Session 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:

CI Failed

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>