Agent Orchestrator: Supervising Parallel AI Coding Agents with Git Worktree Isolation

Two Core Concepts

Agentic IDE differs from a traditional IDE: the IDE is built for humans, with AI as an assistant (e.g., Copilot). An Agentic IDE treats the AI agent as the primary worker and the human as a supervisor who issues tasks and watches the agent’s state.

git worktree is an older Git feature that creates multiple working directories from the same repository, each tied to an independent branch. Switching branches does not require stashing, and files in different worktrees never interfere. Agent Orchestrator creates a worktree per session, giving each agent its own sandboxed directory.

What Is Agent Orchestrator?

In a single sentence, it is a "supervisor of supervisors". Twenty‑three terminal‑type AI coding agents (Claude Code, Codex, Cursor, Kimi Code, opencode, etc.) connect to Agent Orchestrator via adapters. Users create sessions through a desktop app or CLI; each session gets a git worktree, a tmux/conpty terminal, a branch, and a PR. A local daemon continuously monitors session status (active, idle, waiting input, blocked, exited) and routes external signals (PR comments, CI failures, merge conflicts) back to the responsible session so the agent can act automatically.

The orchestrator does not rewrite agents or change their prompts; it merely connects , isolates their workspaces, and routes external events to the right agent.

Problems It Solves

Running multiple Claude Code agents in parallel creates chaos: five terminal windows, five branches, five PRs, five CI logs, and scattered Slack messages. It is impossible to know which agent is stuck or which PR’s CI is running.

Historically teams used three approaches, each with drawbacks:

Manually opening multiple terminals : outputs and PR states are scattered, requiring memory to track each.

Serial queuing : agents run one after another, losing parallelism and wasting time.

Custom coordination scripts : a single maintainer writes scripts to assign worktrees, start tmux, and monitor agents; any new agent adapter breaks the script.

Agent Orchestrator’s approach is to keep agents unchanged and add a unified harness layer:

Traditional: 5 terminals + your brain + your scripts ↓ Agent Orchestrator: 23 agents + a single supervisor

It connects agents, isolates their workspaces, and routes external signals back to the correct session.

How It Works: OBSERVE → UPDATE → DERIVE

The core pipeline consists of three stages.

OBSERVE – SCM Observer and Runtime Reaper continuously pull external facts: PR status, CI results, review comments, merge status, terminal activity, and git events. They only collect facts, not workflow state.

UPDATE – CDC Poller writes these facts into SQLite, storing only atomic facts such as activity<em>state (active/idle/waitinginput/blocked/exited), is<em>terminated, pr, pr<em>checks, and pr<em>comment. Derived display states are never stored.

DERIVE – The service layer reads the persisted facts and computes display states on demand. For example, "working" equals

activity<em>state == 'active' && pr<em>checks all pending

; "ci failed" equals pr<em>checks contain red && not merged.

Storing only facts eliminates bugs caused by state‑synchronisation mismatches; changing derivation logic only affects the read path.

Three Real‑World Scenarios

Parallel feature development : Create five sessions for a large release, each using a different agent (e.g., Claude Code for authentication, Codex for payments, Kimi Code for UI). Worktrees keep files isolated, and the UI shows which session is blocked.

CI failure auto‑feedback : When a session’s PR triggers CI and it fails, the CDC Poller detects the red status and automatically feeds the error log back to the responsible agent, which reads the log, fixes the issue, and re‑runs CI without human intervention.

Review comment loop‑back : Five review comments left on a PR are automatically routed back to the worker session that owns the PR; the agent reads the comments, updates the code, pushes a new commit, and the loop completes without manual clicks.

Technical Architecture

The system is a local daemon architecture: an Electron desktop front‑end + ao CLI in front, a local HTTP daemon (listening on 127.0.0.1) in the middle, and core services plus adapters at the back.

Why Go for a single binary? The daemon must run long‑lived, listen to HTTP/WebSocket, handle concurrent sessions, and be zero‑configuration. Go’s single‑binary output fits perfectly.

Why git worktree instead of Docker? Worktrees are lightweight, create in seconds, and reuse the existing Git toolchain (diff, log, checkout). Docker containers take several seconds to start and break the Git workflow.

Why not store display state? Storing derived states would require updating many dependent fields on every CI status change, leading to concurrency conflicts. Computing the state at read time keeps the write path simple and testable.

Why bind to 127.0.0.1? The daemon is a local tool, not a SaaS service, so it avoids exposing a public endpoint and eliminates the need for authentication.

Why a thick adapter layer? Supporting 23 agents and multiple runtimes would be fragile if implemented in a monolithic class. Each agent lives in its own package, making it easy to drop or update adapters independently.

Core Capabilities

Session layer : Projects contain sessions (each a worktree) with a state machine (active/idle/waiting_input/blocked/exited). The blocked state prevents automated input injection, avoiding accidental operations.

PR feedback layer : Pulls PR creation, CI results, review comments, and merge status, feeding them back to the appropriate session.

Adapter layer : 23 worker agents, multiple reviewer agents, tmux/conpty runtimes, git worktree workspace, and GitHub SCM adapters.

Feedback loop layer : CI failures, review comments, and merge conflicts are automatically fed back to agents for self‑repair, eliminating manual “ops” work.

Integration layer : Electron UI (Tauri‑like but Electron chosen), ao CLI for scripting, optional PostHog telemetry, and experimental pipelines via the AO_PIPELINES env variable.

Installation & Getting Started

Download the appropriate desktop installer from the GitHub Releases page (macOS Apple Silicon/Intel, Linux AppImage, Windows installer). After installation, launch the app, add the repository to manage, and the daemon starts automatically.

The 23 worker agents (Claude Code, Codex, Kimi Code, opencode, Cursor, …) and three reviewer agents each require their own CLI, which the desktop app guides you through on first run. The tool does not force a specific agent; you can mix and match.

See aoagents.dev/docs/installation for detailed steps.

Advantages

Agents remain unchanged; the orchestrator is a supervisor, not a replacement.

Broad adapter coverage (23 workers, multiple runtimes) accommodates mixed‑agent teams.

Git worktree isolation prevents file interference and branch conflicts, with near‑zero overhead compared to containers.

Display state is computed at read time, eliminating synchronization bugs.

Fully automated feedback loops for CI failures, review comments, and merge conflicts reduce manual overhead.

Apache‑2.0 license allows private deployment.

Limitations & Risks

Electron UI consumes more memory than lighter alternatives like Tauri; CLI mode can mitigate this.

Current version is v0.11.2‑nightly; a stable 1.0 release is pending, so production use should be cautious.

Reliance on 23 external agent CLIs means upstream changes may require adapter updates.

The npm CLI is frozen at version 0.10.0; new users must use the desktop app.

Documentation is split across seven sub‑documents, requiring substantial reading for newcomers.

Telemetry is enabled by default (PostHog), though it can be disabled via VITE<em>AO<em>POSTHOG_KEY=''.

Comparison with Similar Tools

Agent support : Agent Orchestrator – 23 workers + 3 reviewers; tmux+manual – any; Crystal – 1 (Codex); Aider – 1 (Aider).

Isolation method : Agent Orchestrator – git worktree; tmux+manual – manual branch handling; Crystal – git worktree; Aider – file lock.

Parallel capability : Agent Orchestrator – native multi‑session; others – limited or none.

CI feedback : Agent Orchestrator – automatic feed‑back; tmux+manual – manual; Crystal – partial; Aider – none.

Review comment handling : Agent Orchestrator – automatic; others – manual or none.

Status visualization : Agent Orchestrator – full dashboard (project/session/terminal/PR); others – terminal output or none.

Deployment : Agent Orchestrator – local daemon + desktop; tmux+manual – none; Crystal – npm package; Aider – pip package.

Maintenance cost : Agent Orchestrator – medium (follow upstream agents); tmux+manual – high; Crystal – medium; Aider – low.

Maturity : Agent Orchestrator – nightly v0.11.2 (pre‑1.0); tmux+manual – mature; Crystal – early; Aider – mature.

License : Agent Orchestrator – Apache‑2.0; others – various.

The core difference is that Agent Orchestrator turns "managing a fleet of agents" into a product, whereas other tools either focus on a single agent or require you to build the coordination yourself.

Who Should Use It

Teams already using Claude Code or Codex for parallel development and need a unified UI to monitor sessions.

Teams wanting to adopt AI agents but worried about management chaos.

Independent developers working on multiple features in parallel.

Researchers studying AI‑agent supervision architectures; the design doc offers valuable patterns such as "store only facts, never derived state" and the OBSERVE/UPDATE/DERIVE pipeline.

It is not suitable for users who only need a single serial agent, cannot tolerate Electron’s resource usage, have only a single development branch, or are new to AI agents and have not installed any agent CLIs yet.

Design Lessons Worth Borrowing

Store only facts, not derived states : Compute UI status on read to avoid synchronization bugs.

Adapters over monolithic frameworks : Isolate each agent in its own package to keep the system extensible.

Feedback loops are infrastructure : Automatic CI and review handling are core, not optional features.

Local daemon > SaaS for personal dev tools : Low latency, zero privacy concerns, and zero deployment cost, at the expense of cross‑device collaboration.

OBSERVE/UPDATE/DERIVE pipeline : Generalizable to any system that pulls external state, persists immutable facts, and derives display information on demand.

Conclusion

Agent Orchestrator adds a supervisory harness to a group of parallel AI coding agents. Agents stay unchanged, workspaces are isolated via git worktree, external signals (CI, review, merge) are automatically fed back, and status is visualized in real time.

It does not replace Claude Code or Codex; it fills the gap of "who supervises a fleet of AI agents when they run in parallel".

Untrivial‑ai maintains the project under Apache‑2.0, with 8.7k+ stars, 1.2k+ forks, written in Go and Electron. The latest commit (2026‑08‑02) shows active development, making it a viable option for teams already using AI coding agents.

GitHub repository:

github.com/Untrivial-ai/agent-orchestrator