81 lines
4.0 KiB
Plaintext
81 lines
4.0 KiB
Plaintext
---
|
|
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>
|