Agent Orchestrator: How 30 AI Agents Built Their Own Management System
Imagine running 5 Claude Code terminal windows, each handling a different issue. You grab a coffee, come back, and find: 3 still running, 1 crashed, 1 finished — but you don't know which branch it pushed to. GitHub shows 5 PRs awaiting review, 2 failing CI, 1 with reviewer comments. You start copy-pasting error logs back into windows, one by one.
Congratulations — you've been demoted from engineer to the worst kind of project manager.
This was pkarnal's (Composio) real experience in February 2026. He held things together with bash scripts, tmux, and git worktrees up to 20 concurrent agents, then realized: the agents aren't the problem; coordinating them is.
8 days later he had 40,000 lines of TypeScript, 3,288 tests, and 17 plugins — most of it written by those 30 agents themselves. The project is open source: Agent Orchestrator (MIT), 6,800+ stars.
1. Building a System in 8 Days — Only 3 Days of Human Work
This wasn't an 8-day hermit sprint. pkarnal had a day job; focused work totaled ~3 days spread over 8.
| Date | Branch commits | Lines added | PRs merged | Notes | |------|---------------|-------------|------------|-------| | Fri 2/13 night | 157 | +30,070 | 1 | Kickoff, ran overnight | | Sat 2/14 | 112 | +5,599 | 27 | Explosive day — everything shipped | | Sun 2/15 | 63 | +4,779 | 5 | Half day | | Mon 2/16 | 68 | +3,575 | 8 | Around day job | | Tue 2/17 | 94 | +9,512 | 4 | Evenings only | | Wed 2/18 | 71 | +2,921 | 11 | Day + evening | | Thu 2/19 | 91 | +3,990 | 4 | Agents all day, evening review | | Fri 2/20 | 0 | — | 1 | Wrap-up |
Totals: 656 branch commits, +76,454 lines, 61 PRs merged.
The pattern: assign tasks before bed → agents work overnight → review and merge in the morning → assign new tasks before work → repeat.
Saturday was the burst: 27 PRs merged in one day — core services, CLI, Web Dashboard, all 17 plugins, npm publish, all at once.
How much was AI-written? 84% of PRs were created by AI sessions, and 100% of commits carry AI co-author trailers identifying which model wrote them. No ambiguity between "human-written" and "machine-written."
2. The Core Idea: You Are the Bottleneck
Most people get the problem wrong.
Agents can write code. That's not the bottleneck. You are.
You spawn five tasks, grab coffee, and 20 minutes later you're refreshing GitHub tabs — waiting on PRs, checking CI, reading review comments. You automated engineering, then replaced it with bad project management.
Agent Orchestrator removes you from that loop. It tracks every session, watches CI, forwards review comments back to agents, and pings you only when human judgment is genuinely needed.
| Without orchestration | With orchestration | |----------------------|-------------------| | Manually create branches | Automatic worktree assignment per issue | | Check each window one by one | Dashboard shows all sessions live | | Manually copy-paste CI errors | Auto-injected into agent sessions | | Forward review comments one by one | Auto-routed to the right agent | | Inspect each PR before merge | Notifications — you only judge | | Dead agents unnoticed | Activity detection catches them |
3. Three Key Designs
1. Git Worktree Isolation
Each agent gets its own git worktree, branch, and PR. Not a full clone — a worktree is a separate working directory of the same repo, sharing the object store, with zero extra storage cost.
This means 30 agents can work on different branches of the same repo simultaneously without interference. Agent A's refactor won't collide with Agent B's bugfix.
2. The Reactions System: Self-Healing CI
The most useful feature. When CI fails, the orchestrator injects the failure log into the agent's session; the agent reads it, fixes the code, and pushes again. When a reviewer requests changes, the orchestrator routes the comment to the right agent, which updates the PR automatically.
Configurable reactions:
ci-failed: auto-handled, up to 2 retries, then escalates to a humanchanges-requested: auto-handled, escalates after 30 minutes unresolvedapproved-and-green: notify only, wait for manual merge (auto-merge optional)- Attention zones — sessions grouped by whether they need you (CI failed, awaiting review, running fine)
- Live terminal — xterm.js embedded in the browser, real-time agent output
- Session detail — files being edited, recent commits, PR status, CI status
- Medium-to-large codebases (too small = unnecessary)
- Solid CI and tests (without CI, reactions can't work)
- A dozen-plus open issues (agents need work)
- A day job and no time to babysit multiple agents
- Willingness to trust agents with most decisions, intervening at key points
- Small personal projects (1–2 agents manually is simpler)
- No CI or test coverage (reactions has nothing to react to)
- Line-by-line review workflows
- Primarily offline environments
- Orchestrator Agent (strategic): split tasks, assign, monitor, decide
- Coding Agents (tactical): read code, write tests, fix bugs, push PRs
- Human (judgment): review, merge, handle escalations
- GitHub: https://github.com/ComposioHQ/agent-orchestrator
- npm: https://www.npmjs.com/package/@aoagents/ao
- Author's blog: https://pkarnal.com/blog/open-sourcing-agent-orchestrator
- Author's GitHub: https://github.com/pkarnal
- Company: Composio (https://composio.dev)
- License: MIT
- Star history: https://star-history.com/#ComposioHQ/agent-orchestrator&Date
All 41 CI failures self-corrected — reactions forwarded them to agents with zero human plumbing.
3. Eight Pluggable Slots
Not either/or — any combination:
| Slot | Default | Options | |------|---------|---------| | Runtime | tmux (macOS/Linux) / process (Windows) | process, docker | | Agent | claude-code | codex, aider, cursor, opencode, kimicode | | Workspace | worktree | clone | | Tracker | github | linear, gitlab | | SCM | github | gitlab | | Notifier | desktop | slack, discord, composio, webhook, openclaw | | Terminal | iterm2 | web | | Lifecycle | core | — (fixed core) |
All interfaces are defined in packages/core/src/types.ts. A plugin implements one interface and exports a PluginModule — that's it.
Note: the Notifier slot includes openclaw, meaning Agent Orchestrator can notify your OpenClaw assistant directly — completed PRs pushed to your chat instead of you watching GitHub.
4. The Orchestrator Itself Is an Agent
This is the fundamental difference from other "run agents in parallel" tools.
> The orchestrator itself is an AI agent. Not a dashboard. Not a cron job. Not a script that polls GitHub.
It reads your codebase, understands the backlog, splits features into parallelizable tasks, assigns coding agents, monitors progress, reads PRs, and decides next steps. CI failure → it decides to inject; review comment → it decides who routes it; PR green → it decides to notify you to merge.
Comparison with alternatives:
| Tool | Positioning | Key difference | |------|-------------|----------------| | Agent Orchestrator | Fully automated PR lifecycle | Orchestrator itself is an AI agent | | Claude Squad | Terminal TUI wrapper | More a session manager, no automatic CI repair | | Microsoft Conductor | YAML workflows | Deterministic orchestration, not intelligent decisions | | Bernstein | Deterministic scheduler | Janitor cleanup, not AI-driven | | Emdash | 22 CLI providers | Electron desktop, parallel dispatch | | Vibe Kanban | Kanban + MCP decomposition | Web app, community-maintained |
Claude Squad is more a "terminal multi-window manager" — helps you switch tmux sessions but doesn't auto-handle CI or reviews. Agent Orchestrator is an "intelligent housekeeper" — run ao start and walk away; come back only to review and merge.
5. Web Dashboard and Remote Access
The Dashboard (Next.js 15, Server-Sent Events for real-time updates, no polling) offers:
macOS sleep is prevented automatically (caffeinate), so you can access the dashboard remotely over Tailscale from your phone. Clamshell mode requires external power + display + input (a hardware limitation).
6. Limitations and Boundaries
1. Agent idle time is longer than expected. In real runs with 4 agents, 2 sessions sat idle 90+ seconds waiting for tool approvals. On token-based billing, that idle cost adds up.
2. Not for offline work. Requires GitHub/Linear connections and CI pipelines. Purely local projects or non-git workflows don't fit.
3. Not for per-edit review. If you want to approve every line change, the automation will conflict with you. It's human-on-the-loop, not human-in-the-loop.
4. Package rename residue. The rename from @composio/agent-orchestrator to @composio/ao may break older tutorials.
5. The OpenClaw notifier is nice but ecosystem-dependent. Without OpenClaw, you're left with desktop/slack/discord/webhook. Notification channels determine when you get pulled back into the loop.
7. Is It for You?
Good fit:
Bad fit:
8. From "Writing Code" to "Herding the Flock"
Agent Orchestrator represents not "AI writes code faster" but a redistribution of engineering roles.
Before: you write, test, debug, and review PRs. Now: you set direction, make key judgments, and merge — writing, testing, and debugging is done by agents, and coordination among agents is done by an orchestrator agent.
Three layers:
pkarnal's run proves the structure works: 8 days, 3 days of focus, 40,000 lines — humans only assign tasks and make final calls.
But this raises a deeper question: when the orchestrator agent gets smart enough, does it become the new bottleneck? It can manage 30 agents today — what if the codebase needs 300? Will "orchestrators of orchestrators" emerge recursively?
Answer: yes, and it's already happening. Vibe Kanban's MCP decomposition is a higher-level coordinator. Agent Orchestrator is single-layer herding; the next layer may be multi-layer herd topologies.
9. One-Line Takeaway
Agent Orchestrator isn't just another AI coding tool — it's a scheduling operating system for AI coding. Eight pluggable slots let you mix and match agents, runtimes, issue trackers, and notification channels; git worktree isolation lets 30 agents run in parallel without conflict; the reactions system closes the loop on CI failures and review comments automatically. And 40,000 lines of TypeScript were mostly written by the agents it manages. This isn't the future — it happened in February 2026.
If you use Claude Code across multiple issues, this system returns your role from "project manager" to "engineer."
---
Project info