Agent Orchestrator: Managing Parallel AI Coding Agents with Git Worktrees
Hook
What if your codebase could handle 20 simultaneous AI coding agents, each working on different issues in complete isolation, automatically fixing their own CI failures and responding to code review feedback without human intervention?
Context
The AI coding assistant landscape has matured rapidly. Tools like GitHub Copilot, Cursor, and Claude Code have proven that AI can write production code. But there’s a fundamental bottleneck: these tools are designed for single-developer workflows. You sit at your terminal, describe what you want, and the AI generates code. When you have 50 GitHub issues to address, you’re stuck context-switching between tasks manually, babysitting each agent, and shepherding code through CI and review cycles.
This orchestration problem becomes acute for teams that want to leverage AI at scale. How do you assign 30 different issues to AI agents simultaneously? How do you prevent them from stepping on each other’s work? When CI fails or a reviewer leaves comments, how do you route that feedback back to the responsible agent? The existing solution has been human coordination—developers manually managing which agent works on what, resolving conflicts, and retriggering agents when tests fail. Agent Orchestrator exists to eliminate that human bottleneck, treating AI coding agents as autonomous workers that can be deployed, monitored, and managed like a distributed system.
Technical Insight
Agent Orchestrator’s architecture solves the parallel agent problem through three key design decisions: git worktrees for workspace isolation, a plugin-based agent abstraction, and reactive feedback loops that close the CI/review cycle automatically.
The worktree approach is elegant. Instead of cloning the repository multiple times or forcing agents to share a single working directory, Agent Orchestrator uses git worktrees—a lesser-known Git feature that creates multiple working directories linked to the same repository. Each agent gets its own branch and working directory, but they share the same .git folder, making branch switching and cleanup trivial. Here’s how the workspace plugin initializes an agent environment:
// Simplified from the workspace plugin
class GitWorktreeWorkspace implements WorkspacePlugin {
async createAgentWorkspace(agentId: string, baseBranch: string): Promise<string> {
const branchName = `agent/${agentId}/${Date.now()}`;
const worktreePath = path.join(this.repoRoot, '.agent-workspaces', agentId);
// Create worktree with new branch
await git.raw(['worktree', 'add', '-b', branchName, worktreePath, baseBranch]);
// Configure isolated git identity for agent
await git.cwd(worktreePath).addConfig('user.name', `Agent ${agentId}`);
await git.cwd(worktreePath).addConfig('user.email', `agent-${agentId}@orchestrator.local`);
return worktreePath;
}
async cleanup(agentId: string): Promise<void> {
const worktreePath = path.join(this.repoRoot, '.agent-workspaces', agentId);
await git.raw(['worktree', 'remove', worktreePath, '--force']);
}
}This design means 20 agents can work simultaneously on the same repository without any file system conflicts. Agent 1 might be refactoring authentication while Agent 2 adds a new API endpoint—they never see each other’s uncommitted changes because they’re in completely separate directories.
The plugin architecture treats agents as black boxes. Agent Orchestrator doesn’t care whether you’re using Claude Code, Aider, or a custom script—it just needs to spawn a process, pass it instructions via stdin, and read results from stdout. The agent plugin interface is intentionally minimal:
interface AgentPlugin {
spawn(config: AgentConfig): Promise<AgentProcess>;
sendTask(process: AgentProcess, task: Task): Promise<void>;
readOutput(process: AgentProcess): AsyncIterator<AgentMessage>;
terminate(process: AgentProcess): Promise<void>;
}This abstraction enables heterogeneous agent fleets. You can run three instances of Claude Code for complex refactoring tasks, two instances of Aider for quick bug fixes, and a custom agent for specialized domain logic—all managed by the same orchestrator. The runtime plugin handles process isolation (defaulting to tmux sessions but swappable for Docker containers or Kubernetes pods), while the tracker plugin connects to your issue system to pull task descriptions and update status.
The reactive feedback system is where Agent Orchestrator becomes truly autonomous. When an agent creates a PR, the orchestrator registers listeners for CI status updates and review comments. If tests fail, the system automatically routes the failure details back to the agent that created the code:
// Simplified feedback loop handler
class CIFeedbackHandler {
async onCIFailure(pr: PullRequest, ciResult: CIResult): Promise<void> {
const agentId = this.getResponsibleAgent(pr);
const agent = this.agentPool.get(agentId);
const retryCount = this.tracker.getRetryCount(pr.id);
if (retryCount >= this.maxRetries) {
await this.notifier.escalateToHuman(pr, ciResult);
return;
}
const feedbackTask = {
type: 'fix-ci',
context: {
originalTask: pr.originalTask,
failedTests: ciResult.failures,
logs: ciResult.logs,
branch: pr.headBranch
}
};
await agent.sendTask(feedbackTask);
this.tracker.incrementRetryCount(pr.id);
}
}This creates a closed loop: agent writes code → creates PR → CI fails → agent receives failure context → agent fixes code → pushes update → CI runs again. The same pattern applies to code review comments. A reviewer leaves feedback, the orchestrator parses it, and sends it to the agent as a new task with full context about what needs to change.
The dashboard and CLI provide visibility into this distributed system. You can see which agents are working on which tasks, view their progress in real-time, and intervene when necessary. The lifecycle plugin system lets you inject custom logic at key points—before task assignment, after PR creation, on CI completion—making the orchestrator extensible for team-specific workflows like security scanning or deployment automation.
Gotcha
Agent Orchestrator’s autonomous features are powerful but come with real risks. The auto-merge capability will merge PRs that pass CI without human review if you enable it. This assumes your test coverage is comprehensive enough to catch all issues—a dangerous assumption for most codebases. A clever agent could write code that satisfies tests but introduces subtle bugs, security vulnerabilities, or architectural problems that only human review would catch. The configuration lets you set trust boundaries and require human approval for certain types of changes, but the documentation doesn’t provide clear guidance on where those boundaries should be. You need to think carefully about what level of autonomy is appropriate for your codebase’s maturity and test coverage.
The infrastructure requirements are significant. You need Node.js 20+, Git 2.25+, tmux, and the GitHub CLI properly configured. The system assumes a Unix-like environment—Windows support appears minimal or nonexistent. Setting up the plugin configuration, integrating with your CI system, and tuning the retry policies requires substantial upfront investment. For small teams or projects with fewer than five simultaneous tasks, this complexity isn’t justified. You’re better off manually managing agents or using simpler automation scripts. Additionally, the system’s value proposition depends entirely on having reliable CI. If your tests are flaky or your CI pipeline is slow, the feedback loops become noise rather than signal, and agents will waste time chasing false failures.
Verdict
Use Agent Orchestrator if you’re managing 10+ parallel coding tasks across a mature codebase with strong test coverage and established CI/CD pipelines. It’s ideal for teams that have already adopted AI coding assistants and need to scale beyond manual coordination. The investment in setup pays off when you’re regularly processing dozens of GitHub issues simultaneously and want to automate the tedious cycle of PR creation, CI fixes, and review responses. Skip it if you’re just exploring AI coding tools, working on projects with weak test coverage (agents need reliable feedback), handling fewer than five concurrent tasks (manual management is simpler), or operating in Windows environments. The orchestrator is powerful infrastructure for scale, but it’s overkill for small-scale automation—start with standalone agents and graduate to orchestration when you hit coordination bottlenecks.
