Running Parallel AI Agents

Run Claude Code, Command Code, and Cursor simultaneously on different branches

GWTree enables you to run multiple AI coding agents in parallel, each working on separate branches in isolated worktrees. This means zero conflicts, no context switching, and faster feature delivery.

Why Parallel Agents?

In the AI-assisted development era, you can leverage multiple coding agents simultaneously:

• Claude Code fixing authentication bugs
• Command Code building API endpoints
• Cursor creating UI components

Each agent works in its own isolated environment without stepping on each other’s toes.

Quick Start

1. Create multiple worktrees instantly

   Create three worktrees for different features in one command:

   gwt auth api dashboard -x
   

   This creates:

   • repo-auth/ with auth branch
   • repo-api/ with api branch
   • repo-dashboard/ with dashboard branch

   The -x flag skips opening editors automatically.

2. Launch agents in each worktree

   Open each worktree with its dedicated agent:

   # Terminal 1: Claude Code on auth
   cd repo-auth
   claude
   

   # Terminal 2: Command Code on API
   cd repo-api
   commandcode
   

   # Terminal 3: Cursor on dashboard
   cd repo-dashboard
   cursor .
   
3. Work in parallel

   Each agent now operates independently:

   • No branch switching conflicts
   • No stash/unstash cycles
   • No context loss between tasks
   • Each agent maintains its own state
4. Monitor progress

   Check status across all worktrees:

   gwt status
   

   This shows changes, commits ahead/behind, and merge status for each worktree.

Real-World Workflow

Bug Fixes

Assign critical bugs to different agents:

gwt bug-auth bug-payment bug-email -x

Each agent can investigate and fix independently.

Feature Development

Split a large feature across multiple agents:

gwt backend-api frontend-ui database-migration -x

Coordinate full-stack development in parallel.

Testing Approaches

Try different implementations simultaneously:

gwt approach-a approach-b approach-c -x

Compare solutions before committing.

Refactoring Tasks

Tackle refactoring modules in parallel:

gwt refactor-auth refactor-api refactor-ui -x

Keep refactoring isolated from new features.

Merging Work

Once an agent completes its work:

# Review the changes
cd repo-auth
git diff main

# Merge and cleanup in one command
gwt merge auth

This automatically:

1. Checks out main
2. Merges the auth branch
3. Removes the repo-auth/ worktree
4. Deletes the auth branch

Best Practices

Keep tasks independent

Assign tasks to agents that don’t overlap in the same files. This prevents merge conflicts and allows true parallel work.

Use descriptive names

Name worktrees clearly to track which agent is working on what:

gwt claude-auth cursor-dashboard commandcode-api -x

Monitor regularly

Use gwt status frequently to track progress across all agents:

gwt st  # Quick status check

Clean up completed work

Remove merged worktrees regularly:

gwt clean  # Remove merged worktrees only
gwt clean --all  # Remove all worktrees

Advanced: Fast Mode

For even faster setup, use -y to skip all prompts:

GWT_EDITOR=none gwt auth api dashboard -y

This uses saved defaults and creates all worktrees instantly.

Troubleshooting

Agent conflicts on same files

If two agents need to work on overlapping code:

1. Let one agent complete and merge first
2. Update main: cd repo && git pull
3. Rebase the other agent’s work: cd repo-feature && git rebase main

Worktree creation fails

Ensure you’re in a git repository and have a clean working directory:

git status  # Check for uncommitted changes
git stash   # Stash changes if needed

Next Steps

Feature Development

Learn the complete feature development workflow with worktrees.

Code Review

Review PRs without disrupting your current work.