Maestro: Orchestrating Multiple AI Coding Agents with Git Worktrees and Batch Automation

Hook

What if you could run three different AI coding agents simultaneously on the same repository—each on its own branch, making conflicting architectural decisions—and never deal with a single merge conflict?

Context

AI coding assistants have evolved from autocomplete suggestions to full-fledged pair programmers that can scaffold entire features, refactor codebases, and debug complex issues. Tools like GitHub Copilot, Claude Code, and OpenAI Codex have fundamentally changed how developers write software. But they share a critical limitation: they're designed for single-session, single-project workflows. You open your editor, chat with one AI about one problem, and when you need to switch contexts—maybe to experiment with a different architectural approach or work on another project—you lose that conversational state.

For developers managing multiple projects or exploring divergent implementation strategies, this becomes a coordination nightmare. You can't easily run two AI agents in parallel on the same codebase without them overwriting each other's changes. You can't automate repetitive AI workflows—like 'update all our API endpoints to use the new authentication pattern'—without babysitting each step. And you certainly can't hand an AI agent a 20-item checklist and let it work overnight. Maestro exists to solve these orchestration problems, treating AI coding agents as managed resources that can be parallelized, automated, and coordinated across complex multi-project workflows.

Technical Insight

Maestro's killer feature is its use of Git worktrees to enable true parallel AI agent execution. Most developers think of Git branches as pointers in a single working directory—you switch between them with git checkout. But Git worktrees let you check out multiple branches into separate directories simultaneously, all sharing the same repository history. Maestro exploits this to give each AI agent its own isolated workspace.

Here's how it works in practice. Imagine you're building a REST API and want to explore two different approaches: one using Express with traditional middleware, another using Fastify with a plugin architecture. You create two tasks in Maestro, each targeting a different branch. Maestro spins up two worktrees:

# Maestro creates something like this behind the scenes
git worktree add ../myproject-express-approach express-middleware
git worktree add ../myproject-fastify-approach fastify-plugins

# Now you have:
# ~/projects/myproject/          (main branch)
# ~/projects/myproject-express-approach/   (express-middleware branch)
# ~/projects/myproject-fastify-approach/   (fastify-plugins branch)

Each AI agent—let's say one Claude Code instance and one using OpenAI Codex—operates in its own directory. They can't step on each other's toes because they're literally working in separate file systems. When they're done, you have two fully-realized implementations on separate branches. You can test both, compare the results, cherry-pick the best parts, or merge the winner. No manual branch switching, no stashing changes, no 'wait, which approach was I working on again?'

The Auto Run feature takes this further by transforming markdown checklists into batch-executable task queues. You write a simple markdown file with a checklist:

## API Modernization Tasks

- [ ] Update user authentication endpoint to use JWT
- [ ] Add rate limiting middleware
- [ ] Implement request validation with Zod
- [ ] Update API documentation
- [ ] Add integration tests for auth flow

Maestro parses this, creates a fresh AI session for each task (ensuring clean context without pollution from previous tasks), and executes them sequentially. Each task gets its own conversation thread, its own set of file changes, and its own commit. The crucial insight here is that Maestro doesn't try to maintain conversation context across tasks—it deliberately starts fresh each time. This prevents context window overflow and reduces hallucination risk because each AI session has a focused, bounded scope.

The architecture is deliberately pass-through. Maestro doesn't intercept or modify the AI provider APIs—it acts as a proxy that preserves Model Context Protocol (MCP) tools and configurations. If you've set up Claude Code with custom MCP servers for database access or API testing, those continue to work unchanged. Maestro just adds a coordination layer on top:

// Simplified view of Maestro's session management
interface AgentSession {
  id: string;
  provider: 'claude' | 'openai' | 'opencode';
  worktreePath: string;
  branch: string;
  conversationHistory: Message[];
  mcpTools: MCPToolConfig[];
}

class SessionOrchestrator {
  private sessions: Map<string, AgentSession>;
  private taskQueue: Task[];
  
  async executeTask(task: Task): Promise<void> {
    // Create isolated worktree
    const worktree = await this.gitManager.createWorktree(task.branch);
    
    // Spawn fresh AI session with clean context
    const session = await this.spawnAgent({
      provider: task.provider,
      worktreePath: worktree.path,
      systemPrompt: task.context,
      mcpTools: this.loadMCPConfig(task.provider)
    });
    
    // Execute and collect results
    await session.execute(task.instructions);
    await this.gitManager.commitChanges(worktree, task.id);
  }
}

The Group Chat feature adds another layer by introducing a moderator AI that routes questions to appropriate agents. If you're working on a full-stack project with one AI handling frontend React code and another managing backend PostgreSQL schemas, you can ask 'How should I structure user profile data?' The moderator analyzes the question, determines it needs input from both agents, queries them independently, and synthesizes a coherent response. It's like having a tech lead who knows which specialist to consult.

Maestro also gamifies keyboard mastery with a progress tracking system that monitors how often you use shortcuts versus reaching for the mouse. Hit milestones (100 keyboard actions, 500, 1000) and you level up, displayed right in the UI. It sounds gimmicky, but it's surprisingly effective at building muscle memory for things like quick-switching between agent sessions (Cmd+1, Cmd+2) or spawning new worktrees without breaking flow. The underlying psychology is sound: immediate feedback reinforces behavior change.

The analytics dashboard visualizes your AI usage patterns—which agents you use most, which projects consume the most tokens, and peak productivity hours. More interesting is the document graph that discovers wiki-style links between your markdown files (using [[double bracket]] notation) and renders them as a knowledge graph. This reveals unexpected connections between projects and helps identify documentation gaps.

Gotcha

Maestro is a coordination layer, not an AI provider. It doesn't include any AI models, doesn't offer free inference, and won't work without API keys for Claude, OpenAI, or other supported providers. Every agent session you run hits your API budget directly. The Auto Run feature is particularly dangerous here—a 24-hour automated session churning through a complex task list could easily burn through hundreds of dollars in API costs if you're not careful. Maestro has no built-in budget caps, no 'stop if costs exceed X' safety rails, and no warnings when you're approaching rate limits. You need to monitor this yourself through your provider's dashboard.

The Git worktree approach, while elegant, assumes you understand Git's data model well enough to not shoot yourself in the foot. If an AI agent makes commits in a worktree and you force-push or rebase carelessly, you can create orphaned commits or confusing history. Maestro doesn't hold your hand here—it gives you powerful primitives but expects you to manage the resulting complexity. Similarly, having multiple worktrees means multiple node_modules directories, multiple build artifacts, and multiple running dev servers consuming disk space and RAM. On a laptop with limited resources, spinning up three parallel agent sessions each with their own worktree can quickly exhaust available memory.

The Electron wrapper means Maestro is a relatively heavyweight desktop application—it's not a nimble CLI tool you can script or integrate into CI/CD pipelines easily. The built-in web server for remote control is a nice touch, but it's not a substitute for proper API-first design if you need programmatic access.

Verdict

Use Maestro if: You regularly juggle multiple AI-assisted projects and lose productivity to context switching; you want to explore divergent architectural approaches simultaneously without merge conflict hell; you have repetitive AI workflows that would benefit from batch automation (like 'update all components to use new design system'); you're a keyboard-first developer who values flow state and wants to minimize mouse usage; or you need to coordinate multiple AI agents across a complex codebase where different agents specialize in different domains. Skip it if: You work on one project at a time and don't need session management overhead; you prefer lightweight CLI tools over Electron apps; you're cost-conscious about AI API usage and want built-in budget controls (Maestro has none); you don't have the Git expertise to safely manage multiple worktrees; or you're looking for an AI coding assistant with included models rather than an orchestration layer. Maestro is transformative for power users managing complex multi-agent workflows but overkill for developers who just want a better Copilot.