---
title: Introduction
description: Learn what Agent Orchestrator does, when to use it, and where to start.
---

import { Callout } from "fumadocs-ui/components/callout";

Agent Orchestrator (**AO**) runs AI coding agents in isolated git worktrees and keeps track of the work until it becomes a pull request.

Use it when you have several well-scoped issues and want agents to work on them at the same time without sharing a checkout, terminal, or branch. AO starts each session, watches the agent, tracks the PR, and shows the state of every session in one dashboard.

<Callout type="info" title="Fastest path">
  If you are new to AO, install it first, then run the quickstart against one small issue. Start with [Installation](/docs/installation), then [Quickstart](/docs/quickstart).
</Callout>

## What AO Is For

AO is useful when you want to:

- Run more than one coding agent at the same time.
- Keep every agent in its own worktree, branch, and session.
- Watch agent terminals and PR state from one dashboard.
- Let AO wake an agent when CI fails or a review requests changes.
- Use different agent CLIs across projects or roles, such as Claude Code, Codex, Cursor, Aider, and OpenCode.

AO works best for issues that have a clear outcome: failing tests, small features, focused refactors, migrations, documentation updates, and review follow-ups.

## What AO Does Not Do

AO does not replace review. It helps agents keep working, but you still decide what gets merged.

| AO handles | You still handle |
| --- | --- |
| Creating isolated workspaces | Choosing good issues |
| Launching and monitoring agents | Reviewing code and behavior |
| Tracking PR, CI, and review status | Deciding when to merge |
| Cleaning up merged sessions | Setting repo-specific rules and expectations |

## How A Session Moves

```text
issue -> ao spawn -> worktree + agent -> pull request -> CI/review loop -> merge -> cleanup
```

The dashboard shows this lifecycle as session cards. Open a card to see the live terminal, current activity state, issue link, PR link, and worktree path.

## How AO Fits Together

AO is built from plugins. The default setup works out of the box for common GitHub workflows, and you can swap pieces when your setup is different.

| Plugin slot | What it controls | Examples |
| --- | --- | --- |
| Agent | Which coding tool writes changes | Claude Code, Codex, Cursor, Aider, OpenCode |
| Runtime | How the agent process runs | tmux, child process |
| Workspace | Where code is checked out | git worktree, full clone |
| Tracker | Where issues come from | GitHub, GitLab, Linear |
| SCM | How PRs, reviews, and CI are read | GitHub, GitLab |
| Notifier | Where AO sends updates | desktop, Slack, Discord, webhook |

Most users start with the defaults and only edit `agent-orchestrator.yaml` when they need a different agent, runtime, tracker, or notification target.

## Platform Support

<PlatformSupport
  macos="full"
  linux="full"
  windows="partial"
  note={<>Windows support is actively improving. Use the process runtime instead of tmux by setting <code>defaults.runtime: process</code> in <code>agent-orchestrator.yaml</code>. See <a href="/docs/platforms">Platforms</a> for details.</>}
/>

## Where To Go Next

<Cards>
  <Card title="Installation" description="Install AO, authenticate your tools, and run the doctor check." href="/docs/installation" />
  <Card title="Quickstart" description="Spawn one agent on one issue and watch it open a PR." href="/docs/quickstart" />
  <Card title="Configuration" description="Understand the `agent-orchestrator.yaml` file." href="/docs/configuration" />
  <Card title="Guides" description="Run parallel issues, recover from CI failures, and handle review loops." href="/docs/guides" />
  <Card title="Plugins" description="See which agents, runtimes, trackers, SCMs, terminals, and notifiers are available." href="/docs/plugins" />
  <Card title="Troubleshooting" description="Fix common install, dashboard, runtime, and session problems." href="/docs/troubleshooting" />
</Cards>