Agent Orchestrator is an orchestration layer designed to manage fleets of parallel AI coding agents operating on a codebase. It addresses the coordination problem inherent in supervising multiple AI agents simultaneously across various issues, branches, and Pull Requests (PRs).

The core methodology of Agent Orchestrator involves isolating each AI agent within its own environment and automating feedback loops from the development workflow. When an agent is spawned using $ao spawn <project> [issue]$, the system performs the following steps:

1. Workspace Creation: It creates an isolated git worktree with a dedicated feature branch for the agent. This ensures code changes are confined and easily managed.
2. Runtime Instantiation: It initiates a runtime environment, defaulting to a tmux session, but with support for docker, k8s, or direct process execution.
3. Agent Launch: An AI agent (e.g., claude-code, codex, aider, opencode) is launched within this runtime, provided with the context of the issue or task.
4. Autonomous Operation: The agent operates autonomously, capable of reading code, writing tests, and creating PRs.
5. Reactive Feedback: The system incorporates a "Reactions" mechanism to handle common development events automatically:
   • CI Failures (ci-failed): If CI fails, the agent receives the logs and attempts to fix the issues, configurable for auto-action and retries.
   • Changes Requested (changes-requested): Upon reviewer requests for changes, the agent automatically addresses them, with an escalation mechanism if unresolved within a specified duration.
   • Approved and Green CI (approved-and-green): When a PR is approved and passes CI, the system can notify the user or be configured for auto-merge.
6. Minimal Human Intervention: A notifier system, defaulting to desktop notifications but supporting slack, composio, or webhooks, pings the user only when human judgment is explicitly required.

The system is built on a highly modular Plugin Architecture, which exposes eight "slots" for swappable abstractions, allowing for extensive customization and integration. Each plugin implements a specific TypeScript interface and exports a PluginModule. The key abstraction slots include:

• Runtime: Manages the execution environment (e.g., tmux default, docker, k8s).
• Agent: Specifies the AI coding model (claude-code default, codex, aider).
• Workspace: Handles code isolation (worktree default, clone).
• Tracker: Integrates with issue tracking systems (github default, linear).
• SCM: Source Code Management platform (github).
• Notifier: Defines how user notifications are delivered (desktop default, slack, webhook).
• Terminal: Specifies the terminal interface (iterm2, web).
• Lifecycle: Core process management (core).

Configuration is managed via an agent-orchestrator.yaml file, which allows setting global defaults for plugins and defining specific project configurations. Project settings include repository owner/path, local path, default branch, and a session prefix. The "Reactions" behavior, including auto-action, retries, and escalation timelines, is also configurable within this file.

The Command Line Interface (CLI) provides essential management functionalities: ao status for an overview of all sessions, $ao spawn <project> [issue]$ to initiate an agent, $ao send <session> "instructions"$ to send arbitrary instructions to a running agent, ao session ls to list active sessions, $ao session kill <session>$ to terminate a session, $ao session restore <session>$ to revive a crashed agent, and ao dashboard to open the web-based supervisory dashboard, which operates on http://localhost:3000.

The system automates isolation, feedback routing, and status tracking, reducing manual overhead for developers who can then focus on reviewing PRs and making critical decisions. Prerequisites for installation include Node.js 20+, Git 2.25+, tmux (for default runtime), and gh CLI (for GitHub integration). Development involves pnpm install, pnpm build, pnpm test, and pnpm dev for the dashboard. The project encourages contributions, particularly through its plugin system.