> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CodeGroup>
  ```yaml CI Failed theme={null}
  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
  ```

  ```yaml Review Comments theme={null}
  reactions:
    changes-requested:
      auto: true              # Enable auto-handling
      action: send-to-agent   # Send review comments to agent
      escalateAfter: 30m      # Escalate if not resolved in 30 min
  ```

  ```yaml Auto-merge theme={null}
  reactions:
    approved-and-green:
      auto: false             # Disabled by default (flip to true)
      action: auto-merge      # Merge when approved + CI passes
      priority: action
  ```
</CodeGroup>

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:

```bash theme={null}
ao spawn my-project 123
```

The orchestrator executes this workflow:

<Steps>
  <Step title="Create Workspace">
    Creates an isolated git worktree (or clone) with a feature branch
  </Step>

  <Step title="Start Runtime">
    Launches a tmux session (or Docker container, etc.) for the agent
  </Step>

  <Step title="Spawn Agent">
    Starts the AI agent (Claude Code, Codex, Aider) with issue context
  </Step>

  <Step title="Autonomous Work">
    Agent reads code, writes tests, commits changes, and creates a PR
  </Step>

  <Step title="Automatic Reactions">
    System auto-handles CI failures and review comments via reactions
  </Step>

  <Step title="Human Notification">
    You receive a notification only when your judgment is needed
  </Step>
</Steps>

## Architecture Overview

Agent Orchestrator is built as a TypeScript monorepo using pnpm workspaces:

```text theme={null}
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>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.