Skillget

parallel-cc

skill
Security Audit
Fail
Health Pass
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 12 GitHub stars
Code Fail
  • rm -rf — Recursive force deletion command in scripts/uninstall.sh
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Automated parallel management of Claude Code versions using Git worktrees and autonomous coordination between agents in separate terminals

README.md

parallel-cc

Follow on X
Version
Node.js
TypeScript
License: MIT

Coordinate parallel Claude Code sessions using git worktrees + E2B cloud sandboxes for autonomous execution.

parallel-cc enables both interactive and autonomous Claude Code workflows:

  • Local mode: Parallel worktree coordination for interactive development
  • E2B Sandbox mode: Long-running autonomous execution in isolated cloud VMs
  • Parallel Sandbox mode (NEW): Execute multiple tasks simultaneously across sandboxes

Table of Contents

Features

Local Parallel Sessions

  • Automatic worktree creation - No manual setup required
  • SQLite-based coordination - Fast, reliable session tracking
  • Auto-cleanup - Worktrees removed when sessions end
  • Heartbeat monitoring - Detect and clean up stale sessions
  • Zero configuration - Works out of the box
  • Merge detection - Know when parallel branches are merged
  • Conflict checking - Preview rebase conflicts before they happen
  • MCP integration - Claude can query session status and assist with rebases
  • File claims - Coordinate exclusive/shared file access across parallel sessions
  • Conflict resolution - Track and resolve semantic, structural, and concurrent edit conflicts
  • Auto-fix suggestions - AI-generated conflict resolutions with confidence scores
  • AST analysis - Deep semantic conflict detection using abstract syntax trees

E2B Sandbox Execution

  • Cloud sandboxes - Execute Claude Code in isolated E2B VMs
  • Long-running tasks - Up to 1 hour of uninterrupted execution
  • Security hardened - Shell injection prevention, input validation, resource cleanup
  • Intelligent file sync - Compressed upload/download with selective sync
  • Cross-process reconnection - Access sandboxes created in separate CLI invocations
  • Full CLI control - Run, monitor, download, and kill sandbox sessions
  • Cost tracking - Automatic warnings at 30min and 50min usage marks
  • Branch management - Auto-generate branches, custom naming, or uncommitted changes
  • Git Live mode - Push directly to remote and create PRs automatically
  • Dual authentication - Support for both API key and OAuth methods

Parallel Sandbox Execution (NEW in v2.1)

  • Multi-task execution - Run multiple tasks simultaneously across E2B sandboxes
  • Configurable concurrency - Control max parallel sandboxes (default: 3)
  • Fail-fast mode - Stop all tasks on first failure
  • Progress monitoring - Real-time status updates for each task
  • Per-task isolation - Each task gets its own worktree and sandbox
  • Result aggregation - Summary reports with timing and success metrics
  • Time savings - Execute tasks in parallel vs sequentially

The Problem

When you open multiple Claude Code sessions in the same repository, they can step on each other:

  • Git index locks when both try to commit
  • Build artifacts conflict
  • Dependencies get corrupted
  • General chaos ensues

The Solution

parallel-cc automatically detects when you're starting a parallel session and creates an isolated git worktree for you. Each Claude Code instance works in its own space, then changes merge cleanly.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    Session Startup Flow                      │
├─────────────────────────────────────────────────────────────┤
│  1. You run: claude-parallel (or aliased 'claude')           │
│  2. Wrapper checks for existing sessions in this repo        │
│  3. If parallel session exists → creates worktree via gtr    │
│  4. Wrapper cd's into worktree, then launches claude         │
│  5. Claude Code works in isolated worktree                   │
│  6. On exit → session released, worktree cleaned up          │
└─────────────────────────────────────────────────────────────┘

Requirements

  • Node.js 20+
  • gtr - Git worktree management
  • jq - JSON parsing in wrapper script

Installation

# Clone and install (interactive)
git clone https://github.com/frankbria/parallel-cc.git
cd parallel-cc
./scripts/install.sh

# Or non-interactive installation with all features
./scripts/install.sh --all

The install script will:

  1. Check all dependencies (Node.js 20+, git, jq, gtr)
  2. Build the TypeScript project
  3. Install CLI and wrapper scripts to ~/.local/bin
  4. Create the database directory
  5. Verify installation with parallel-cc doctor
  6. Prompt to install heartbeat hooks (global or local) - or install automatically with --all
  7. Provide shell-specific setup instructions

Non-interactive installation:
Use ./scripts/install.sh --all to install everything automatically:

  • Installs heartbeat hooks globally (~/.claude/settings.json)
  • Configures shell alias (claude=claude-parallel)
  • Sets up MCP server integration
  • No prompts, ideal for automation/CI/CD

Advanced Installation

Custom installation directory:

export PARALLEL_CC_INSTALL_DIR="$HOME/bin"
export PARALLEL_CC_DATA_DIR="$HOME/.config/parallel-cc"
./scripts/install.sh

Uninstall:

./scripts/uninstall.sh

The uninstall script offers to remove configurations (hooks, alias, MCP) before removing installed files. Session data is preserved unless manually deleted.

Recommended: Create an alias

Add to your ~/.bashrc or ~/.zshrc:

alias claude='claude-parallel'

Now every time you run claude, it automatically handles parallel coordination!

Optional: Complete Setup with One Command

For the best experience, run the full installation which sets up both the heartbeat hook and shell alias:

# Full installation (recommended)
parallel-cc install --all

# Or step-by-step:
parallel-cc install --hooks --global  # Heartbeat hook
parallel-cc install --alias           # Shell alias

# Interactive mode - prompts for each option
parallel-cc install --interactive

# Check installation status
parallel-cc install --status

Or add manually to ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.local/bin/parallel-cc-heartbeat.sh"
          }
        ]
      }
    ]
  }
}

Usage

Just open multiple terminals and run claude (or claude-parallel) in each:

# Terminal 1
cd ~/projects/myrepo
claude  # Gets the main repo

# Terminal 2
cd ~/projects/myrepo
claude  # Automatically gets a worktree!
# Output: 📂 Parallel session detected - working in worktree
#         Path: /home/user/projects/myrepo-worktrees/parallel-m4x2k9...

That's it! Each session is isolated. When you're done, just exit claude normally - the worktree is cleaned up automatically.

CLI Commands

System & Installation

# Check system health
parallel-cc doctor

# Installation & configuration
parallel-cc install --all                # Install everything (hooks + alias + MCP)
parallel-cc install --interactive        # Prompted installation
parallel-cc install --hooks              # Interactive hook installation
parallel-cc install --hooks --global     # Install hooks globally
parallel-cc install --hooks --local      # Install hooks locally
parallel-cc install --alias              # Add claude=claude-parallel alias
parallel-cc install --alias --uninstall  # Remove alias
parallel-cc install --mcp                # Configure MCP server in Claude settings
parallel-cc install --status             # Check installation status

# Database management
parallel-cc migrate                      # Migrate to latest version (1.0.0)
parallel-cc migrate --version 1.0.0      # Migrate to specific version

Session Management

# Show active sessions
parallel-cc status
parallel-cc status --repo /path/to/repo
parallel-cc status --json
parallel-cc status --sandbox-only        # Show only E2B sandbox sessions

# Session lifecycle (usually handled by wrapper)
parallel-cc register --repo /path/to/repo --pid $$
parallel-cc release --pid $$
parallel-cc cleanup                      # Clean up stale sessions

Merge & Conflict Management

# Merge detection
parallel-cc watch merges                 # Start merge detection daemon
parallel-cc watch merges --once          # Run single merge detection poll
parallel-cc merge status                 # Show merge events history
parallel-cc merge status --subscriptions # Show active merge subscriptions

# File claims & conflict resolution
parallel-cc claims                       # List active file claims
parallel-cc claims --file src/app.ts     # Filter by file path
parallel-cc conflicts                    # View conflict resolution history
parallel-cc conflicts --type SEMANTIC    # Filter by conflict type
parallel-cc suggestions                  # List auto-fix suggestions
parallel-cc suggestions --min-confidence 0.8  # Filter by confidence threshold

E2B Sandbox Execution

# Run Claude Code in cloud sandbox
parallel-cc sandbox run --repo . --prompt "Implement feature X"
parallel-cc sandbox run --repo . --prompt-file PLAN.md

# Authentication options
parallel-cc sandbox run --repo . --prompt "Fix bug" --auth-method api-key  # Use ANTHROPIC_API_KEY
parallel-cc sandbox run --repo . --prompt "Fix bug" --auth-method oauth    # Use Claude subscription

# Branch management
parallel-cc sandbox run --repo . --prompt "Add feature" --branch auto               # Auto-generate branch + commit
parallel-cc sandbox run --repo . --prompt "Fix issue #42" --branch feature/issue-42 # Specify branch name
parallel-cc sandbox run --repo . --prompt "Refactor"                                # Default: uncommitted changes

# Git Live mode - Push and create PR automatically
parallel-cc sandbox run --repo . --prompt "Fix bug" --git-live
parallel-cc sandbox run --repo . --prompt "Add feature" --git-live --target-branch develop
parallel-cc sandbox run --repo . --prompt "Fix #42" --git-live --branch feature/issue-42

# Monitoring & control
parallel-cc sandbox logs --session-id <id>       # View sandbox logs
parallel-cc sandbox logs --session-id <id> --follow  # Stream logs in real-time
parallel-cc sandbox download --session-id <id>   # Download results without terminating
parallel-cc sandbox kill --session-id <id>       # Terminate running sandbox

# Testing
parallel-cc sandbox run --dry-run --repo .       # Test setup without execution

Parallel Sandbox Execution (NEW in v2.1)

# Execute multiple tasks in parallel
parallel-cc sandbox run --repo . --multi --task "Implement auth" --task "Add tests" --task "Update docs"

# Load tasks from file (one task per line)
parallel-cc sandbox run --repo . --multi --task-file tasks.txt --max-concurrent 5

# Fail-fast mode (stop all on first failure)
parallel-cc sandbox run --repo . --multi --task "Task 1" --task "Task 2" --fail-fast

# Combined with other options
parallel-cc sandbox run --repo . --multi --task "Feature A" --task "Feature B" --auth-method oauth --max-concurrent 2

Configuration & Budget

# Configuration management
parallel-cc config set <key> <value>     # Set configuration value
parallel-cc config get <key>             # Get configuration value
parallel-cc config list                  # Display all config values

# Budget tracking
parallel-cc budget status                # Show budget/spending status

# Templates
parallel-cc templates list               # List sandbox templates
parallel-cc templates show <name>        # Show template details

How Sessions Work

  1. First session in a repo gets the main repository
  2. Subsequent sessions automatically get a new worktree
  3. Heartbeats track active sessions (optional PostToolUse hook)
  4. Stale detection cleans up crashed sessions after 10 minutes
  5. Auto-cleanup removes worktrees when sessions end

Configuration

Default config (in src/types.ts):

{
  dbPath: '~/.parallel-cc/coordinator.db',
  staleThresholdMinutes: 10,
  autoCleanupWorktrees: true,
  worktreePrefix: 'parallel-'
}

Merging Work from Worktrees

After working in a worktree, you'll want to merge your changes:

# In the worktree, commit your changes
git add .
git commit -m "feat: my feature"

# Option 1: Push and create PR
git push -u origin $(git branch --show-current)
# Then create PR on GitHub/GitLab

# Option 2: Merge directly to main
cd ~/projects/myrepo  # Go to main repo
git merge <worktree-branch-name>

E2B Sandbox Integration

Run autonomous Claude Code sessions in isolated cloud sandboxes for truly hands-free development.

Quick Start

# Prerequisites: E2B account and API key
export E2B_API_KEY="your-key-here"

# One-time setup: Migrate database to v1.0.0 for E2B features
parallel-cc migrate --version 1.0.0

# Step 1: Plan interactively (local)
cd ~/projects/myrepo
claude  # Create PLAN.md with implementation steps
git commit PLAN.md -m "plan: feature implementation"

# Step 2: Execute autonomously (E2B sandbox)
parallel-cc sandbox run --repo . --prompt "Execute PLAN.md with TDD approach"
# Walk away - Claude works unattended for 30+ minutes in isolated sandbox

# Step 3: Review results
cd parallel-e2b-abc123  # worktree with completed work
git diff main
pytest tests/  # verify locally
git push origin HEAD:feature/my-feature

Why E2B Sandboxes?

  • Truly Autonomous: Execute long-running tasks (up to 1 hour) without supervision
  • Safe Execution: Sandboxes run with --dangerously-skip-permissions safely in isolated VMs
  • Plan-Driven: Claude autonomously follows PLAN.md or custom prompts step-by-step
  • Real-Time Monitoring: Stream output and check progress anytime
  • Cost-Effective: ~$0.10/hour for E2B compute time
  • Git Integration: Results automatically committed in worktrees for easy review

Parallel Sandbox Execution (NEW in v2.1)

Execute multiple tasks simultaneously across E2B sandboxes for maximum throughput.

Basic Usage:

# Run 3 tasks in parallel
parallel-cc sandbox run --repo . --multi \
  --task "Implement user authentication" \
  --task "Add unit tests for API endpoints" \
  --task "Update documentation"

Load Tasks from File:

# tasks.txt (one task per line)
# Implement feature A
# Add tests for feature A
# Update API documentation

parallel-cc sandbox run --repo . --multi --task-file tasks.txt

Configurable Concurrency:

# Limit to 2 parallel sandboxes (default: 3)
parallel-cc sandbox run --repo . --multi --task "Task 1" --task "Task 2" --task "Task 3" --max-concurrent 2

# Run up to 5 sandboxes simultaneously
parallel-cc sandbox run --repo . --multi --task-file large-task-list.txt --max-concurrent 5

Fail-Fast Mode:

# Stop all tasks immediately if any task fails
parallel-cc sandbox run --repo . --multi --task "Critical setup" --task "Dependent work" --fail-fast

How Parallel Execution Works:

  1. Each task gets its own isolated worktree via the Coordinator
  2. Each task runs in its own E2B sandbox instance
  3. Results are downloaded to separate directories under ./parallel-results/
  4. A summary report is generated with timing metrics and success rates

Output Structure:

parallel-results/
├── task-1/           # Results from first task
├── task-2/           # Results from second task
├── task-3/           # Results from third task
└── summary-report.md # Execution summary with metrics

Benefits:

  • Time Savings: Run 3 one-hour tasks in ~1 hour instead of ~3 hours
  • Isolation: Tasks can't interfere with each other
  • Visibility: Real-time progress updates for each task
  • Flexibility: Mix with other options (auth, templates, budget limits)

Branch Management Modes

1. Uncommitted Changes (Default)

parallel-cc sandbox run --repo . --prompt "Fix issue #84"
# Results downloaded as uncommitted tracked files
# Full control: review with git status/diff, then commit manually

Benefits:

  • Full control over commit message and branch name
  • Review changes before committing
  • Stage changes selectively

2. Auto-Generated Branch

parallel-cc sandbox run --repo . --prompt "Fix issue #84" --branch auto
# Creates: e2b/fix-issue-84-2025-12-13-23-45
# Auto-commits with descriptive message

Benefits:

  • One-step branch creation and commit
  • Descriptive branch name from prompt
  • Ready to push immediately

3. Custom Branch Name

parallel-cc sandbox run --repo . --prompt "Fix issue #84" --branch feature/issue-84
# Creates specified branch and commits

Benefits:

  • Control over branch naming convention
  • Matches team's branch patterns
  • One-step creation and commit

Git Live Mode

What is Git Live Mode?

Git Live Mode (--git-live) pushes results directly to a remote feature branch and creates a pull request automatically, bypassing the local download workflow. Perfect for autonomous "walk away" tasks.

Quick Example:

# Basic git-live: Push and create PR automatically
parallel-cc sandbox run --repo . --prompt "Fix bug" --git-live

# With custom target branch (default: main)
parallel-cc sandbox run --repo . --prompt "Add feature" --git-live --target-branch develop

# Full example with all options
parallel-cc sandbox run \
  --repo . \
  --prompt "Implement auth system" \
  --auth-method oauth \
  --git-live \
  --target-branch main \
  --branch feature/auth-system

What Happens:

  1. Execution completes in E2B sandbox
  2. Changes committed in sandbox with descriptive message
  3. Feature branch pushed to remote (auto-generated or custom name)
  4. Pull request created using gh CLI
  5. PR URL returned immediately

Requirements:

Parallel Session Warning:

When --git-live is used with multiple parallel sessions active, you'll see a warning prompt. You can choose to:

  • Continue (y): Proceed with git-live, accepting potential PR conflicts
  • Switch (n): Automatically fall back to download mode

When to Use Git Live:

  • Single autonomous task with clear scope
  • No other parallel sessions active
  • Want immediate PR for review
  • Trust the execution quality
  • "Walk away and review later" workflow

When to Use Download Mode (Default):

  • Multiple parallel sessions
  • Want to review changes before committing
  • Need to stage changes selectively
  • Interactive development workflow

Authentication Methods

1. API Key Authentication (Default)

export ANTHROPIC_API_KEY="sk-ant-api03-..."
parallel-cc sandbox run --repo . --prompt "Task" --auth-method api-key

2. OAuth Authentication

# First, login within Claude Code session
claude
/login  # Follow prompts

# Then use OAuth mode
parallel-cc sandbox run --repo . --prompt "Task" --auth-method oauth

Usage Examples

# Basic execution with TDD approach
parallel-cc sandbox run --repo . --prompt "Implement feature X with tests"

# Execute from plan file
parallel-cc sandbox run --repo . --prompt-file PLAN.md

# Full example with OAuth and auto branch
parallel-cc sandbox run \
  --repo . \
  --prompt "Implement auth system" \
  --auth-method oauth \
  --branch auto

# Git Live mode with custom branch
parallel-cc sandbox run \
  --repo . \
  --prompt "Fix issue #123" \
  --git-live \
  --branch feature/issue-123 \
  --target-branch develop

# Parallel execution with multiple tasks
parallel-cc sandbox run \
  --repo . \
  --multi \
  --task "Implement feature A" \
  --task "Implement feature B" \
  --task "Add integration tests" \
  --max-concurrent 3

Setup Requirements

  1. E2B Account: Sign up at https://e2b.dev (free tier available)
  2. E2B API Key: Set E2B_API_KEY environment variable
  3. Claude Authentication (choose one):
    • API Key: Set ANTHROPIC_API_KEY (pay-as-you-go)
    • OAuth: Run /login in Claude Code (uses your Pro subscription)
  4. GitHub Token (for git-live mode): Set GITHUB_TOKEN environment variable
  5. Cost Awareness: E2B charges ~$0.10/hour for sandbox compute time

See docs/E2B_GUIDE.md for complete setup instructions and troubleshooting.
See docs/REFERENCE.md for database schema, MCP tools, and technical specifications.

What's New

v2.1.0 - Parallel Sandbox Execution (February 2026)

New Features:

  • Parallel Task Execution - Execute multiple tasks simultaneously across E2B sandboxes
    • --multi flag enables parallel mode
    • --task option (repeatable) for specifying multiple tasks
    • --task-file option to load tasks from a file
    • --max-concurrent to control parallelism (default: 3)
    • --fail-fast to stop all tasks on first failure
  • Per-Task Isolation - Each task gets its own worktree and sandbox
  • Progress Monitoring - Real-time status updates for each parallel task
  • Result Aggregation - Summary reports with timing metrics and success rates
  • Improved Input Validation - Enhanced validation for --multi mode arguments

v2.0.0 - CLI Modernization (February 2026)

Breaking Changes:

  • Subcommand Structure - Commands now use proper subcommand format
    • sandbox run instead of sandbox-run
    • mcp serve instead of mcp-serve
    • watch merges instead of watch-merges
    • Old hyphenated commands still work with deprecation warnings
    • Will be removed in v3.0.0

New Features:

  • Budget Tracking - Set daily/weekly/monthly spending limits
  • Config Management - config set/get/list commands for settings

v1.0.0 - Git Live Mode & Enhanced Branch Management (December 2024)

New Features:

  • Git Live Mode - Autonomous PR creation directly from E2B sandboxes

    • Push results to remote branches automatically
    • Create pull requests with gh CLI integration
    • Parallel session detection and warnings
    • Configurable target branches

  • Enhanced Branch Management

    • --branch auto - Auto-generate descriptive branch names from prompts
    • --branch <name> - Custom branch naming
    • Default mode: Uncommitted changes for full control
    • Smart branch name slugification (max 50 chars, kebab-case)

  • Installation Improvements

    • ./scripts/install.sh --all - Non-interactive installation
    • Automatic setup of hooks, alias, and MCP server
    • Ideal for automation and CI/CD pipelines

Security Enhancements:

  • Shell injection prevention in git commit messages
  • Branch name validation and sanitization
  • Target branch validation
  • Input validation for all E2B commands

Bug Fixes:

  • Fixed GITHUB_TOKEN passing to gh CLI in sandboxes
  • Improved error handling in OAuth authentication
  • Better file sync reliability for E2B downloads
  • Migration system improvements with automatic updates

See ROADMAP.md for detailed version history and future plans.

Roadmap

Current Version: v2.1

Core Features:

  • Parallel worktree coordination with automatic session management
  • SQLite-based session tracking with heartbeat monitoring
  • MCP server integration with 16 tools for Claude Code
  • Branch merge detection and rebase assistance
  • Advanced conflict resolution with AST analysis
  • AI-powered auto-fix suggestions with confidence scoring
  • E2B sandbox integration for autonomous execution
  • Plan-driven workflows with real-time monitoring
  • Git Live mode for autonomous PR creation
  • Sandbox templates (Node.js, Python, Next.js)
  • SSH key injection for private repositories
  • Budget tracking and cost controls
  • Modern subcommand CLI structure
  • Parallel sandbox execution (multiple tasks simultaneously)

What's Next

v2.2 - Enhanced Parallel Features (Planned)

  • Pause/resume functionality for long-running tasks
  • Enhanced cost reporting and analytics per task
  • Custom sandbox templates from project detection
  • Task dependency graphs for sequential-then-parallel workflows

See ROADMAP.md for detailed specifications, implementation plans, and complete version history.

Troubleshooting

"parallel-cc not found"

Make sure ~/.local/bin is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

"gtr not found"

Install gtr from https://github.com/coderabbitai/git-worktree-runner

Note: parallel-cc supports both:

  • gtr v1.x (standalone gtr command)
  • gtr v2.x (git gtr subcommand)

The tool auto-detects which version you have installed.

Sessions not cleaning up

Run manual cleanup:

parallel-cc cleanup

Check system health

parallel-cc doctor

This checks dependencies (gtr, git, jq), database location, configuration, and MCP server status.

E2B Sandbox Issues

"E2B API key not found"

export E2B_API_KEY="your-key-here"

"Claude authentication failed"

  • For API key mode: Set ANTHROPIC_API_KEY
  • For OAuth mode: Run /login in Claude Code first

"Git Live mode - GITHUB_TOKEN required"

export GITHUB_TOKEN="ghp_..."  # Get from https://github.com/settings/tokens

Parallel Execution Issues

"ParallelExecutor requires at least one task"

  • Ensure you're using --task or --task-file with --multi

Tasks completing too slowly

  • Increase --max-concurrent (but watch E2B costs)
  • Check individual task complexity

Fail-fast not stopping other tasks

  • This is expected for tasks already running; only pending tasks are cancelled

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

MIT © Frank Bria

Built with TypeScript, SQLite, and git worktrees

Reviews (0)

No results found