How Agent Orchestrator Uses Git Worktrees to Run Parallel AI Coding Agents
Hook
What if your CI failures fixed themselves before you finished your morning coffee? Agent Orchestrator spawns parallel AI coding agents that autonomously handle CI errors, review comments, and merge conflicts—each working in its own git worktree branch without stepping on each other’s toes.
Context
Modern development teams drown in parallelizable work: bug fixes, test additions, dependency updates, documentation improvements. These tasks pile up in issue trackers because they’re too small to prioritize but too numerous to ignore. Meanwhile, AI coding assistants like Claude and Aider excel at well-scoped tasks but operate as single-threaded tools—one developer, one chat session, one task at a time.
Agent Orchestrator breaks this bottleneck by treating AI agents as a managed fleet rather than individual assistants. Point it at a repository and it spawns multiple agents simultaneously, each tackling a different issue in an isolated git worktree. When CI fails on a PR, the agent that created it automatically receives the failure logs and fixes the problem. When a reviewer requests changes, the agent addresses the feedback without human intervention. You supervise from a dashboard, only jumping in when human judgment is actually needed. This is orchestration-as-code for AI agents—infrastructure that turns parallelizable issues into concurrent PRs instead of sequential interruptions to your flow state.
Technical Insight
The core architectural insight is using git worktrees for true filesystem-level isolation. When you run ao start https://github.com/your-org/your-repo, the orchestrator doesn’t just manage multiple chat sessions pointing at the same directory. It creates separate worktrees—distinct working directories that share the same .git repository but operate on different branches simultaneously. Issue #42 gets worktree issue-42 on branch agent/issue-42, while issue #73 works in issue-73 on agent/issue-73. No file locks, no merge conflicts between agents, no waiting for one to finish before the next starts.
This worktree strategy appears in the default workspace configuration:
defaults:
runtime: tmux
agent: claude-code
workspace: worktree # Each agent gets its own directory
notifiers: [desktop]
projects:
my-app:
repo: owner/my-app
path: ~/my-app
defaultBranch: main
sessionPrefix: appWhen an agent spawns, Agent Orchestrator creates a new tmux session (or Docker container, depending on your runtime plugin), runs git worktree add to provision an isolated directory, and launches the configured AI agent (Claude Code, Aider, or Codex) inside it. The agent reads the issue description from GitHub or Linear, writes code, commits changes, and opens a PR—all in its own sandbox.
The second architectural pillar is the reaction system, which implements autonomous feedback loops without human intervention. This is where Agent Orchestrator graduates from “parallel task runner” to “self-healing build system.” The reactions config defines how the orchestrator responds to events:
reactions:
ci-failed:
auto: true
action: send-to-agent # Route failure logs back to the agent
retries: 2
changes-requested:
auto: true
action: send-to-agent
escalateAfter: 30m # Notify human after 30 minutes
approved-and-green:
auto: false # Set to true for auto-merge
action: notifyWhen CI fails on a PR created by agent issue-42, the orchestrator captures the build logs via the GitHub SCM plugin, identifies which tmux session owns that PR (tracked internally by session ID to branch mapping), and injects the error output into the agent’s context. The agent reads the failure, debugs the code, pushes a fix, and the CI runs again—automatically, up to the configured retry limit. Same pattern for code review comments: the orchestrator polls for review events, routes comments to the responsible agent, and the agent addresses feedback without waking you up. Only when an agent exhausts retries or hits the escalateAfter timeout do you get a desktop notification asking for human input.
The plugin architecture keeps all this coordination logic generic. Seven interface slots—Runtime, Agent, Workspace, Tracker, SCM, Notifier, Terminal—let you swap implementations without touching the orchestrator core. Want to replace tmux with Docker containers? Swap the runtime plugin. Prefer Linear issues over GitHub? Change the tracker plugin. The orchestrator doesn’t care; it just manages lifecycle (spawn, route feedback, escalate) while plugins handle environment-specific details. This separation of concerns is why the same orchestrator can manage Claude Code agents in tmux worktrees on macOS and Codex agents in Docker containers on Linux without code changes.
The dashboard at http://localhost:3000 gives you a God’s-eye view of all active sessions: which issues are being worked on, which PRs are open, which agents are waiting on CI, which need escalation. Click into any session and you can see the agent’s tmux session in real time or attach to it for manual debugging. The orchestrator agent—a meta-agent that watches for new issues and spawns worker agents—runs continuously in the background, turning your issue tracker into a work queue that empties itself. The project’s own demo shows agents building features for Agent Orchestrator itself, a recursion that demonstrates the system’s stability under self-referential workloads.
Gotcha
The infrastructure prerequisites are non-trivial. You need Node.js 20+, Git 2.25+, tmux, and the GitHub CLI (gh) installed and authenticated before ao start works. This is manageable on macOS and Linux (where tmux is a brew install or apt install away), but Windows users face significant friction—tmux doesn’t run natively on Windows, so you need WSL2 or a Docker-based runtime plugin. The README explicitly lists these dependencies but doesn’t sugarcoat the setup burden. If your team runs mixed platforms or can’t install system-level dependencies, the tmux default becomes a dealbreaker.
The reaction system’s autonomy cuts both ways. Setting auto: true on approved-and-green enables auto-merge, which sounds appealing until you consider edge cases: agents can’t evaluate whether a PR satisfies business logic requirements, security implications, or architectural consistency. They operate purely on syntactic feedback—CI passed, reviewer said “LGTM,” so merge. If your review process relies on implicit human judgment beyond explicit comments (“this technically works but violates our unwritten convention about error handling”), auto-merge will create technical debt. The escalateAfter timeout helps but requires tuning per-project: 30 minutes may be too aggressive for teams expecting multi-hour review latency. There’s no built-in support for “require two approvals” or “block merge if certain files changed” policies—you’d need to implement those as custom reaction plugins or rely on branch protection rules outside the orchestrator.
Verdict
Use Agent Orchestrator if you have a sustained backlog of multiple parallelizable issues (bug fixes, test additions, documentation updates) and want AI agents to handle routine CI failures and review feedback autonomously. It’s designed for teams that already use AI coding assistants and want to scale from one-agent-at-a-time to fleet-level throughput. The git worktree isolation is well-tested (evidenced by 61 merged PRs and 3,288 test cases), and the plugin architecture means you’re not locked into Claude or GitHub—swap agents and trackers as your stack evolves. Skip it if you’re tackling one-off tasks where the orchestration overhead exceeds the benefit, lack the infrastructure prerequisites (especially on Windows without WSL2), or require strict human review of every code change before merge. The system is designed for managing concurrent agent sessions regularly, not occasionally. For occasional AI pair programming, stick with single-agent tools like Cursor or GitHub Copilot.
