Agent orchestrator: stop parallel coding conflicts now

With 1,629 commits and 8.1k stars, the Agent Orchestrator repository answers one narrow question: how do you run terminal agents like Claude Code, Codex or Aider on the same repository at once without them overwriting each other. The answer is one git worktree per session, plus a daemon that sends CI failures and merge conflicts back to the session that caused them. The rest of the design follows from those two decisions.

The analysis draws on the architecture of the public agent-orchestrator project, which uses Go and TypeScript to manage session state and pull request awareness. By using patterns found in the OpenAI Agents SDK for manager-style coordination, teams can deploy these tools to handle complex coding tasks. This setup ensures that while individual agents execute code, the orchestrator maintains oversight of branches and review comments across the entire development lifecycle.

Why Every Session Gets Its Own Worktree

Agent Orchestrator as a Meta-Use for Parallel AI Coding

Agent Orchestrator functions as the orchestration layer supervising parallel AI coding agents within isolated git worktrees. This meta-use architecture enables terminal-based tools to execute simultaneously without file contention or branch conflicts. Race conditions vanish when the system allocates a dedicated worktree per session, a sharp contrast to shared development environments where coding sessions increasingly involve multi-file edits. The supervisor maintains durable state for every worker, routing CI failures and merge conflicts directly to the responsible agent's context window.

Operators gain a unified view of supported worker types, all coordinated through a single daemon. Manual terminal juggling gives way to managed agentic coordination, where the orchestrator handles logistics while workers focus on code generation.

Operators choose isolated workspaces when concurrent edits risk corrupting the working directory or confusing agent context. Disk usage rises; maintaining multiple checkouts increases storage overhead compared to shared environments. A network interruption would force a full context reload without durable state tracking, wasting tokens and time. Review comments and platform events map precisely to the active session that generated the code. Builders gain visibility into which agents are blocked or finishing, enabling precise intervention only when human judgment is required.

Validating the Agent Orchestrator Repository Structure and License

Active maintenance and structural stability appear clearly in the commit history of the agent-orchestrator repository. The project relies on a Go backend comprising 67.0% of the codebase, paired with a TypeScript frontend at 24.5%, ensuring strong performance for terminal-based agents. Current metrics show 8.1k stars, 1.2k forks, and 27 watchers. Distinct backend and frontend directories sit alongside packages in the repository structure, reflecting a separation of concerns between the local daemon and the desktop control surface. The project is licensed under Apache License 2.0, which regulated workflows should confirm by auditing the LICENSE file rather than the repository page.

Inside the Feedback Loop of Automated Code Supervision

CDC Broadcasting and Isolated Git Worktree Mechanics

CDC broadcasting routes state changes from a local daemon to desktop interfaces, ensuring every session update reaches the correct observer without polling delays. This mechanism underpins the Review feedback loop by instantly transmitting CI failures or merge conflicts to the specific agent session responsible for the affected code. Without this directed signal propagation, parallel agents would lack the context necessary to resolve errors autonomously, forcing manual intervention.

The architecture prevents file mixing by placing every session in a separate git worktree. When a user initiates a task, the system spawns an isolated environment where the agent operates independently. This isolation guarantees that branching strategies and terminal outputs remain distinct, even when 78% of sessions involve multi-file edits across the same repository.

Maintaining distinct worktrees requires the daemon to manage multiple git contexts simultaneously, and that is the price of a guarantee standard agents cannot give: no two of them write into the same working directory. The Live terminal control feature relies on the same separation to attach users to specific worker terminals without exposing unrelated process noise.

Routing CI Failures and Review Comments to Specific Agents

The local daemon watches session state, terminal activity, pull requests, CI, and review feedback to route events precisely. This mechanism identifies a build failure or comment and directs the payload to the correct isolated git worktree.

Operational flow relies on four distinct steps:

1. The supervisor detects a status change in the continuous integration pipeline.
2. Metadata maps the error to a specific branch and session ID.
3. The daemon pushes the failure log directly into the worker terminal.
4. The agent ingests the new input and initiates a repair loop.

This process supports the Review feedback loop by allowing reviewer agents to inspect status and route requested changes back efficiently. Unlike manual coordination, this automated handoff eliminates the latency where context switches typically degrade performance. A key limitation is that all worker agents must run within the supported terminal runtime to receive these injected signals.

Consequently, the architecture enforces a hard boundary where agents cannot accidentally modify files outside their assigned scope. This constraint ensures that even if an agent hallucinates a destructive command, the damage remains confined to a single disposable worktree. For teams managing parallel agent sessions, this isolation is the primary safety mechanism enabling high-concurrency development without fear of repository corruption.

Tmux versus Conpty Runtimes for Agent Terminal Control

Agent Orchestrator launches the selected coding agent within that session's specific terminal runtime to enable direct interaction. The system supports two primary backend modes for this execution: tmux for persistent session management and conpty for native Windows console emulation. Choosing between them dictates how the supervisor maintains live terminal control while keeping session summaries visible.

The tmux approach allows operators to detach from a worker terminal without stopping the underlying agent process, preserving state across network interruptions. Conversely, conpty provides strict adherence to Windows console protocols, ensuring that agents relying on native Win32 API calls function correctly without emulation layers. A limitation of the tmux model on non-native systems is the potential for escape-sequence misinterpretation if the host terminal emulator lacks full compatibility.

This architectural choice directly impacts the reliability of the review feedback loop. If the runtime fails to correctly stream stdout back to the daemon, CI failure notifications may not trigger the automatic routing logic. Operators on Unix-like systems generally prefer tmux for its durability, while Windows developers must rely on conpty to avoid breaking agent tool use. The correct configuration ensures that every coded solution remains observable and interruptible by the human supervisor.

The 23 Supported Worker Harnesses and Reviewer Agents

Agent Orchestrator acts as a meta-use layer unifying 23 distinct worker agent harnesses into one supervision point. The system includes adapters for claude-code, codex, aider, opencode, grok, droid, amp, agy, crush, cursor, qwen, copilot, goose, auggie, continue, devin, cline, kimi, kiro, kilocode, vibe, pi, and autohand. This design follows a strict rule: if a tool runs in a terminal, it runs on Agent Orchestrator. Reviewer agents function separately to supervise these workers without sharing terminal memory, enabling users to inspect review status and route requested changes back to the correct worker session.

Loss of shared local context defines the operational cost; agents cannot implicitly reference a colleague's uncommitted scratchpad because the isolated workspaces strictly enforce boundary constraints. That trade only pays above a certain concurrency: with 57% of organizations now deploying multi-step agent workflows in production, manual coordination is the part that stops scaling first.

Configuring the Agent Orchestrator Environment

Agent Orchestrator Installation Paths and CLI Entry Points

Running npm install -g @aoagents/ao followed by ao start offers the quickest setup path. Engineers preferring pnpm, yarn, or source installs for custom runtime requirements have those options available too.

Executing ao start binds the daemon to the current git worktree immediately. Isolated sessions spring up for parallel agents as soon as the daemon is running. Detailed backend mental models and lifecycle persistence logic live in docs/architecture.md, so engineers should consult that file before customizing adapter configurations.

Configuring GitHub Tokens and Local Telemetry Controls

A GitHub personal access token allows the supervisor to access remote repository state and post status checks. Telemetry transmission to PostHog occurs by default in the Electron renderer to track reliability metrics. Session recording captures interface interactions but redacts local paths and local URLs before leaving the host machine. Setting VITE_AO_POSTHOG_KEY to an empty string prior to building the application disables this transmission entirely. This configuration prevents any outbound network requests to the analytics provider while retaining full local functionality.

1. Export your GitHub personal access token in the shell session.
2. Define the build variable to suppress telemetry if needed.
3. Execute the start command to initialize the daemon with these settings.

Operator control takes priority over passive data collection here.

Validating Daemon Boundaries and Backend Code Structure

Verification begins by mapping daemon boundaries against the mental model set in docs/architecture.md. This document establishes the lifecycle persistence and status derivation logic required for stable operation.

1. Inspect the backend directory to ensure concern separation matches the documented architecture.
2. Validate that CLI route mappings in the daemon correspond to the expected service endpoints.
3. Confirm that CDC streams correctly isolate session state across parallel agent instances.

Rapid iteration often conflicts with strict adherence to these structural contracts. Builders must treat these documentation files as authoritative specifications rather than optional reading. Ignoring the set backend concern locations results in unpredictable behavior during merge conflict resolution. The orchestration layer cannot guarantee isolated execution contexts without this structural integrity.

References

• SWE-bench Verified tests agents against real GitHub issues, and
• AI Agent Orchestrator in 2026: 9 Frameworks, 5 Patterns
• AI Agent Orchestration for Developers: The Complete 2026 Guide
• OpenCode 2026: Setup Guide for the Top Open-Source AI