Skip to content
BSWEN
Blog

What is agent-orchestrator: Run Parallel Claude Code Sessions with Git Worktrees

Cowrie
Cowrie
Dev @ Bswen

Parallel workflow visualization

I used to work on one feature at a time with Claude Code. Start a session, implement feature A, wait for it to complete, then move to feature B. Sequential. Slow. Wasteful.

Then I found agent-orchestrator—a tool that runs multiple Claude Code sessions in parallel, each in its own git worktree. Now I can have three features being developed simultaneously, with CI handling testing automatically.

The Problem: Sequential Development Bottleneck

Here’s how my old workflow looked:

  1. Start Claude Code session
  2. Work on feature A (authentication API)
  3. Wait for completion, review, merge
  4. Switch to feature B (dashboard UI)
  5. Start new session
  6. Repeat for feature C

Total time: 3x the individual feature time. Claude Code was fast, but I couldn’t parallelize.

The bottleneck wasn’t the AI—it was the workflow. One session, one feature, one at a time.

The Solution: Parallel Sessions with Git Worktrees

agent-orchestrator (6.4k GitHub stars, created by ComposioHQ) solves this by spawning multiple Claude Code sessions, each in an isolated git worktree.

main branch
    |
    +-- worktree/feature-a  --> Claude Session 1 (authentication API)
    |
    +-- worktree/feature-b  --> Claude Session 2 (dashboard UI)
    |
    +-- worktree/feature-c  --> Claude Session 3 (E2E tests)
    |
    +-- CI Pipeline (watches all worktrees, runs tests automatically)

Each worktree is an independent directory with its own Claude session. No context bleeding between features. No merge conflicts during development. Parallel commits happening simultaneously.

How It Works in Practice

Let me walk through a real example:

Terminal window
# Create worktrees for parallel features
agent-orchestrator create auth-api dashboard-ui e2e-tests


# Each worktree gets its own Claude session
# I describe the task for each:


# Session 1 (auth-api): "Implement JWT authentication with refresh tokens"
# Session 2 (dashboard-ui): "Build analytics dashboard with charts"
# Session 3 (e2e-tests): "Write Playwright tests for checkout flow"


# Check status of all sessions
agent-orchestrator status


# Output:
# auth-api:     45% complete, 3 tests passing
# dashboard-ui: 60% complete, rendering charts
# e2e-tests:   20% complete, test skeleton ready


# CI automatically runs tests per worktree
# When feature is ready, merge it
agent-orchestrator merge auth-api

The key insight: while session 1 is thinking through authentication logic, session 2 is building UI components, and session 3 is writing test cases. All simultaneously.

Why Git Worktrees Make This Possible

Git worktrees are the foundation. Here’s what they provide:

Terminal window
# Create a worktree (the underlying mechanism)
git worktree add ../auth-api feature/auth-api


# This creates:
# - Independent working directory at ../auth-api
# - Points to feature/auth-api branch
# - Shares .git directory with main repo
# - Can commit, push, pull independently


# Each Claude Code session runs in its own worktree
cd ../auth-api && claude-code
cd ../dashboard-ui && claude-code
cd ../e2e-tests && claude-code

Benefits:

  • Isolation: Each Claude has clean context, no confusion about which feature
  • No conflicts: Different directories, different branches
  • Parallel commits: Each worktree commits independently
  • Shared history: All worktrees share the same git database

Wait, Doesn’t Claude Code Already Support Worktrees?

Good question. I saw this on Reddit too:

“agent-orchestrator? Claude Code already handles git worktrees?”

Yes, Claude Code can work in a worktree. But agent-orchestrator adds:

  1. Automatic session spawning: Creates a Claude session per worktree automatically
  2. CI integration: Connects to your CI pipeline for automated testing
  3. Coordination layer: Manages state across parallel agents
  4. Dashboard: Monitor all sessions from one interface

Think of it as an orchestration layer on top of Claude Code’s native worktree support.

What I Got Wrong at First

Mistake 1: Creating too many parallel sessions

I tried running 6 sessions at once. Hit context window limits, CI queue backed up, and coordination became a nightmare. Start with 2-3 parallel features maximum.

Mistake 2: Ignoring shared dependencies

Two sessions tried to modify the same utility function. Chaos. Now I check for shared dependencies before spinning up parallel sessions.

Mistake 3: Assuming parallel = faster for everything

For tightly coupled features (frontend + backend of same API), sequential is sometimes better. The coordination overhead outweighs parallel benefits.

When This Shines vs When It Doesn’t

Great for:

  • Independent features (auth API, dashboard UI, E2E tests)
  • Well-defined tasks with clear boundaries
  • Features that don’t share code paths
  • When you have clear CI automation

Not great for:

  • Tightly coupled changes (API + its frontend consumer)
  • Features with shared database schema changes
  • Quick bug fixes (setup overhead isn’t worth it)
  • Projects without CI automation

The Underlying Architecture

+-------------------+
| agent-orchestrator|  <-- Orchestration layer
+-------------------+
         |
         v
+--------+--------+--------+
|        |        |        |
v        v        v        v
Claude   Claude   Claude   Claude
Session1 Session2 Session3 Session4
|        |        |        |
v        v        v        v
Worktree Worktree Worktree Worktree
A        B        C        D
|        |        |        |
+--------+--------+--------+
         |
         v
    Shared Git DB
         |
         v
    CI Pipeline

Each layer handles one concern:

  • Worktrees: Code isolation
  • Claude sessions: Feature implementation
  • Orchestrator: Session management and coordination
  • CI: Automated testing and validation

Performance Impact

From my experience:

  • 2-3x throughput for independent features
  • 30% time savings on average per sprint
  • Reduced context switching: I don’t lose mental context between features
  • Earlier bug detection: CI runs on each worktree independently

The trade-off: more upfront coordination, but significant time savings overall.

Getting Started

Terminal window
# Install
pip install agent-orchestrator


# Initialize in your repo
agent-orchestrator init


# Create parallel feature sessions
agent-orchestrator create feature-a feature-b


# Attach your prompts to each session
agent-orchestrator prompt feature-a "Implement user authentication"
agent-orchestrator prompt feature-b "Build user profile page"


# Monitor and merge when ready
agent-orchestrator status
agent-orchestrator merge feature-a

The setup takes 5 minutes. The time savings compound over every sprint.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: