Preface¶

Since 2026, terminal coding Agents such as Claude Code, Codex, and Cursor have rapidly gained widespread adoption. Developers have begun to get used to “letting Agents write code, open PRs, and run tests”. However, when running 3, 10, or even 30 Agents in the same repository at the same time, the problem is no longer “whether the model is smart enough”, but branches stepping on each other, lost terminal windows, broken CI builds with no one following up, and Review comments not knowing which session to assign to.

In February 2026, the Composio team open-sourced Agent Orchestrator (AO for short), positioning it as an “orchestration layer for parallel coding Agents”. After launching on the GitHub repository composiohq/agent-orchestrator, the project has surpassed 8,700 stars. The official website aoagents.dev describes it as a meta-harness agent IDE — Agents are still responsible for writing code, while AO takes charge of managing multiple parallel workflows.

This article is based on the official README, documentation, and publicly available information from the official website, sorting out what problems AO solves, how its architecture is designed, and its relationship with Git Worktree and CI automated feedback loops.

What Problems Does It Solve?¶

Opening a single Agent terminal is not complicated: switch branches, paste in an Issue, and wait for it to finish modifying the code. The difficulty arises with scaled parallelism:
- Each task requires an independent branch and workspace to avoid file overwrites;
- Multiple tmux/terminal sessions need a unified view to know which ones are running and which are stuck;
- PR CI failures, Review comments, and merge conflicts must be routed back to “the Agent that wrote this code”, instead of manually copying logs back and forth between GitHub and the terminal;
- Clean up worktrees and temporary branches after tasks are completed.

The official documentation summarizes the above manual coordination as a coordination nightmare. AO’s design goal is to turn “multi-Agent parallel development” into a supervised, looped managed workflow: you describe the outcome, and the orchestrator splits tasks and spawns worker Agents, only pushing notifications when human judgment is needed.

Composio’s official blog mentions that AO originated from experiments using bash scripts to manage a small number of Claude Code sessions. After the stable version of the orchestrator went live, the internal team once achieved a throughput of “about 30 PRs per day, all manually reviewed”. A large amount of the project’s own code was submitted and merged by Agents in worktrees managed by AO — this is part of its “bootstrapping” narrative, but for readers, what is more worthy of attention is whether the orchestration layer abstraction is reusable.

Core Workflow: From Task to Merge¶

AO’s high-level loop is clearly laid out in the README, which can be summarized in six steps:
1. Add the Git project to be managed in the desktop app or CLI;
2. Launch a Session for a specific Issue or task;
3. AO creates an isolated Git Worktree for this Session (the default option, which can be switched to a full clone);
4. Launch the specified coding Agent in the selected Runtime (default is tmux, but Docker, Kubernetes, e2b, etc. are also available);
5. The local Daemon continuously monitors Session status, terminal activity, PRs, CI, and Review events;
6. The desktop app/CLI/mobile Kanban displays the global status, and sends follow-up instructions to the corresponding Session when necessary.

Each Session corresponds to “one Agent + one task + one branch + usually one PR”, with a lifecycle from spawn to merge or termination. Sessions are temporary, and worktrees can be destroyed after merging to avoid cluttering the repository with stale branches.

A typical CLI entry (from the documentation example):

ao spawn my-project 123

Where 123 can be a GitHub Issue number. The orchestrator will create a worktree, spin up the Agent, and inject the Issue context into the session.

Pluginized Architecture: Eight Replaceable Slots¶

AO uses a TypeScript monorepo, with the core idea that almost all external dependencies are connected via plugins. The official documentation lists 8 slots:

This design aligns with Composio’s experience in Agent tool integration: coding Agents themselves continue to evolve, and the orchestration layer switches underlying CLIs through unified interfaces without being tied to a single model or IDE.

The architecture documentation also emphasizes several engineering principles: the orchestrator has no central database, using flat metadata files to persist state; Shell calls use execFile instead of string-concatenated exec; external inputs are validated. For scenarios where multiple Agents need to run long-term on a local machine, these details directly impact security and debuggability.

23 Worker Agent Harnesses: Agent-Agnostic Meta-Harness¶

AO currently provides adapters for 23 Worker Agent Harnesses, the full list from the official README is as follows:
claude-code、codex、aider、opencode、grok、droid、amp、agy、crush、cursor、qwen、copilot、goose、auggie、continue、devin、cline、kimi、kiro、kilocode、vibe、pi、autohand

The Review环节 is configured separately, and the currently supported Reviewer Harnesses are: claude-code、codex、opencode.

The official website’s slogan is If it runs in a terminal, it runs on Agent Orchestrator. For teams that already heavily use Claude Code or Cursor CLI, this means they do not need to switch their preferred tools, and only need to hand over “parallel scheduling, isolation, and CI loops” to AO.

Each project can specify a default Worker Agent and Orchestrator Agent (both can be set to Claude Code in the official website example). New Sessions will spin up the corresponding CLI according to the project configuration, keeping the workflow consistent.

Git Worktree: The Key to Parallelism Without Conflicts¶

The most common accident in multi-Agent parallel development is shared working directories. AO uses Git Worktree as the default workspace isolation method:
- Shares the .git directory with the main repository, creating quickly and taking up little disk space;
- Each Session checks out its own feature branch in an independent worktree;
- Suitable for local development scenarios; if stronger isolation is needed, you can switch to a full clone.

This aligns with the idea of developers manually running git worktree add and opening multiple terminals, but AO automates creation, binding Session metadata, destruction and recycling, and associates it with PR/CI status. When multiple Agents modify different modules of the same repository at the same time, worktrees avoid the typical conflict of “Agent A hasn’t committed yet, and Agent B has already modified the same file”.

Automated Feedback Loop for CI and Reviews¶

A frequently discussed feature of AO is Reactions — automated responses to events such as CI failures, Review change requests, and merge conflicts.

Official documentation example (YAML configuration snippet):

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
    escalateAfter: 2
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m
  approved-and-green:
    auto: false
    action: auto-merge

The meaning can be summarized as:
- CI Failure: Automatically send the failure log back to the Session that owns this branch, and the Agent will attempt to fix it; notify humans only after several consecutive failures;
- Review Request for Changes: Route the comment to the corresponding Worker Agent;
- Approved + All CI Checks Pass: Optional automatic merge (disabled by default, needs to be explicitly enabled).

The Observer流程 demonstrated on the official website is: PR check fails on GitHub → AO receives the event → locates the owning Session → Agent opens the relevant test files and continues modifying. This essentially productizes the manual loop of “CI breaks → copy logs → paste back to Agent”, and is one of the core value points that distinguish AO from “single-terminal Agent IDEs”.

The Kanban board divides Sessions into columns such as Working, Needs you, In review, Ready to merge, etc., displaying the Agent type, branch name, and PR status on each card, reducing the cognitive burden as parallel scale increases.

Installation and Usage Methods¶

As of August 2026, AO recommends installing via the desktop application, which supports macOS (Apple Silicon / Intel), Windows, and Linux (AppImage). After installation, point to the local Git repository, and the desktop version will automatically start the Daemon without needing to configure the CLI separately.

The legacy npm global package @aoagents/ao is still available, but the README marks version 0.10.0 as the final version on npm, and new users should prioritize downloading the desktop build. Existing CLI users who run ao start will pull the same build as the desktop version.

The mobile app can pair with the desktop via LAN or Tailscale to view the Kanban, open terminals, and receive “Needs you” push notifications — code execution and modification still take place locally, and the mobile side is mainly a monitoring entry point.

The project is open-sourced under the Apache License 2.0. The Electron rendering process sends anonymous usage events to PostHog (this can be disabled by clearing VITE_AO_POSTHOG_KEY during build). If you have requirements around telemetry before use, you can read docs/telemetry.md.

Relationship with Tools Such as Cursor and Claude Code¶

Many developers ask: I already use Cursor or Claude Code, do I still need AO?

The official FAQ positions it as: a single-Agent, single-terminal scenario may not necessarily require an orchestration layer; AO brings obvious benefits when you need to handle multiple Issues in parallel in the same repository and want CI/Review to automatically return to the corresponding Agent. Cursor, Claude Code, Codex, etc. are the execution layer; AO is the fleet scheduling layer, and the two are complementary rather than substitutable.

In 2026, the Agent toolchain is being layered: models and coding CLIs are competing at the lower layer, while worktree isolation, PR lifecycle, and event-driven Reactions are precipitating into reusable infrastructure at the upper layer. AO’s GitHub star growth rate reflects the community’s consensus on the demand for “parallel Agent engineering”, not just another AI editor.

Summary¶

Agent Orchestrator wraps up the key challenges of parallel coding Agents — isolation, visibility, loops, and lifecycle — into an open-source orchestrated IDE: 23 terminal Agents connect via plugins, the default Git Worktree ensures branches do not interfere with each other, and Reactions automatically send CI failures and Review comments to the correct Session.

If you already use Claude Code, Codex, or Cursor CLI for daily development but still use spreadsheets or manually track “which terminal corresponds to which PR”, it is worth trying AO locally to evaluate whether it can push your Agent fleet from “working” to “mergeable”. Source code and documentation:
- GitHub: https://github.com/composiohq/agent-orchestrator
- Official website and documentation: https://aoagents.dev/