Claude Launcher

A Rust CLI tool that launches multiple Claude AI instances in separate iTerm tabs to work on tasks in parallel. Specialized for Elm and Lamdera development, with built-in support for Test-Driven Development (TDD) using lamdera-program-test.

What it does

claude-launcher opens new iTerm tabs, each running Claude with a specific task. Each Claude instance:

1. Changes to the directory where you ran the command
2. Reads the .claude-launcher/todos.json file in that directory
3. Executes the assigned task
4. Updates .claude-launcher/todos.json to mark the task as complete with a comment
5. Stops after completing the task

Automatic Task Detection

When run without arguments, claude-launcher automatically:

• Reads .claude-launcher/todos.json to find the next phase with TODO status
• Launches all TODO tasks in that phase in parallel
• Phase CTOs automatically spawn the next phase when complete

Step-by-Step Mode

For debugging or when tasks must run sequentially:

claude-launcher --step-by-step

• Runs only the first TODO task in the current phase
• Each task calls claude-launcher --step-by-step when done
• Ensures only one agent is active at a time
• Useful for debugging or when tasks have dependencies

Git Worktree Integration

Claude Launcher supports running each phase in isolated git worktrees, allowing parallel development without branch conflicts. This implements Anthropic's recommended workflow for running parallel Claude Code sessions, with additional automation and management features.

Features

• Isolated Execution: Each phase runs in its own git worktree
• Automatic Management: Worktrees are created and cleaned up automatically
• Parallel Development: Multiple phases can be developed simultaneously
• Branch Management: Each worktree gets its own branch (claude-phase-{id}-{timestamp})
• State Tracking: Track which phases are running in which worktrees

Configuration

Add worktree configuration to .claude-launcher/config.json:

{
  "name": "Your Project",
  "agent": {
    "before_stop_commands": []
  },
  "cto": {
    "validation_commands": [],
    "few_errors_max": 3
  },
  "worktree": {
    "enabled": false,
    "naming_pattern": "claude-phase-{id}-{timestamp}",
    "max_worktrees": 5,
    "base_branch": "main",
    "auto_cleanup": true
  }
}

Configuration Options

• enabled: Enable worktree mode by default (default: false)
• naming_pattern: Pattern for worktree names (supports {id} and {timestamp})
• max_worktrees: Maximum number of worktrees to keep (default: 5)
• base_branch: Branch to create worktrees from (default: "main")
• auto_cleanup: Automatically remove completed worktrees (default: true)

Usage

Run with Worktrees

# Run next phase in a worktree
claude-launcher --worktree-per-phase

# Or enable in config and use auto mode
claude-launcher

List Active Worktrees

claude-launcher --list-worktrees

Output:

Claude Launcher Active Worktrees
================================

Found 2 worktree(s):

1. claude-phase-1-20240115_143022
   Path: ../claude-phase-1-20240115_143022
   Branch: claude-phase-1-20240115_143022
   Created: 20240115_143022
   Phase ID: 1
   Status: Active
   Phase: Foundation Setup
   Progress: 1 TODO, 2 IN PROGRESS, 1 DONE

2. claude-phase-2-20240115_144512
   Path: ../claude-phase-2-20240115_144512
   Branch: claude-phase-2-20240115_144512
   Created: 20240115_144512
   Phase ID: 2
   Status: Completed
   Phase: Feature Implementation
   Progress: 0 TODO, 0 IN PROGRESS, 4 DONE

Clean Up Worktrees

# Manual cleanup
claude-launcher --cleanup-worktrees

# Automatic cleanup happens when:
# - auto_cleanup is enabled
# - A phase is marked as completed
# - max_worktrees limit is exceeded

Workflow Example

1. Initialize Project

   claude-launcher --init
   

2. Configure Worktrees Edit .claude-launcher/config.json to enable worktrees:

   {
     "name": "Your Project",
     "agent": {
       "before_stop_commands": []
     },
     "cto": {
       "validation_commands": [],
       "few_errors_max": 3
     },
     "worktree": {
       "enabled": true,
       "max_worktrees": 3
     }
   }
   

3. Create Task Plan

   claude-launcher --create-task "Implement new feature"
   

4. Execute with Worktrees

   claude-launcher  # Auto mode with worktrees
   

5. Monitor Progress

   claude-launcher --list-worktrees
   

6. Merge Completed Work When a phase is completed, the worktree branch can be merged:

   git merge --no-ff claude-phase-1-20240115_143022
   

Benefits

• Isolation: Each phase's changes are isolated from others
• Parallel Work: Multiple Claude instances can work on different phases simultaneously
• Easy Rollback: If a phase fails, simply delete the worktree
• Clean History: Each phase gets its own branch with clear commits
• No Conflicts: Phases can't interfere with each other's changes

Troubleshooting

Worktree Creation Fails

• Ensure you're in a git repository
• Check that the base branch exists
• Verify you have sufficient disk space

Can't Remove Worktree

• Check if you have uncommitted changes in the worktree
• Use --cleanup-worktrees for safe removal
• Manually remove with git worktree remove -f <path>

State File Issues

• State is tracked in .claude-launcher/worktree_state.json
• Delete this file to reset worktree tracking
• Run --list-worktrees to rebuild state

Prerequisites

• macOS (uses AppleScript to control iTerm)
• iTerm2 installed
• Claude CLI installed and configured
• Rust (for building from source)

Installation

From Source

1. Clone this repository:

   git clone https://github.com/CharlonTank/claude-launcher.git
   cd claude-launcher
   

2. Run the install script (requires sudo to install to /usr/local/bin):

   ./install.sh
   

Manual Build

cargo build --release
sudo cp target/release/claude-launcher /usr/local/bin/

Usage

# Initialize a new project
claude-launcher --init

# Initialize with Lamdera preset
claude-launcher --init-lamdera

# Smart initialization (analyzes your project)
claude-launcher --smart-init

# Generate task phases from requirements
claude-launcher --create-task "your project requirements"

# Auto-launch next available tasks
claude-launcher

# Or manually launch specific tasks
claude-launcher "Phase 1, Step 1A: Task name" "Phase 1, Step 1B: Another task"

Commands

• --init: Creates .claude-launcher/ directory with empty config and todos.json
• --init-lamdera: Creates .claude-launcher/ with Lamdera preset configuration
• --smart-init: Analyzes your project and creates appropriate configuration
• --create-task "requirements": Analyzes your requirements and generates detailed task phases
• No arguments: Automatically detects and launches the next TODO phase (parallel execution)
• --step-by-step: Runs tasks sequentially, one at a time
• --worktree-per-phase: Run each phase in its own git worktree
• --list-worktrees: List all active claude-launcher worktrees
• --cleanup-worktrees: Clean up completed worktrees

Workflow

1. Initialize your project:

   # For a generic project
   claude-launcher --init
   
   # For a Lamdera project
   claude-launcher --init-lamdera
   
   # To auto-detect your project type
   claude-launcher --smart-init
   

   This creates a .claude-launcher/ directory with config.json and todos.json files.

2. Generate task phases:

   claude-launcher --create-task "I want to build a REST API with user authentication and todo management"
   

   Claude will analyze your requirements and create detailed phases with parallel tasks.

3. Launch agents:

   # Automatic mode - launches next TODO phase
   claude-launcher
   
   # Or manually launch specific tasks
   claude-launcher "Phase 1, Step 1A: Create database schema" "Phase 1, Step 1B: Setup Express server"
   

Directory Structure

Claude Launcher uses a .claude-launcher/ directory to store configuration and task tracking:

.claude-launcher/
├── config.json    # Project-specific validation commands and settings
└── todos.json     # Task phases and progress tracking

config.json

The configuration file defines validation commands that CTOs will run and commands available to agents:

{
  "name": "Project Name",
  "agent": {
    "before_stop_commands": [],
    "commands": [
      {
        "description": "Add internationalization keys",
        "pattern": "elm-i18n add --fr \"French text\" --en \"English text\" KEY_NAME",
        "use_instead_of": "editing src/I18n.elm directly"
      }
    ]
  },
  "cto": {
    "validation_commands": [
      {
        "command": "npm test",
        "description": "Run tests"
      },
      {
        "command": "npm run lint",
        "description": "Check code quality"
      }
    ],
    "few_errors_max": 5
  },
  "worktree": {
    "enabled": false,
    "naming_pattern": "claude-phase-{id}-{timestamp}",
    "max_worktrees": 5,
    "base_branch": "main",
    "auto_cleanup": true
  }
}

Agent Commands

The commands array allows you to define project-specific commands that agents should use instead of directly editing files. This is particularly useful for:

• Code generation tools
• Internationalization (i18n) management
• Database migrations
• Schema updates
• Any tool that manages file updates programmatically

When commands are configured, agents will be instructed to use these commands rather than manually editing the specified files.

todos.json

The task file contains phases and steps:

{
  "phases": [
    {
      "id": 1,
      "name": "Core Setup",
      "steps": [
        {
          "id": "1A",
          "name": "Create database schema",
          "prompt": "Create a PostgreSQL schema with users and todos tables...",
          "status": "TODO",
          "comment": ""
        }
      ],
      "status": "TODO",
      "comment": ""
    }
  ]
}

Elm/Lamdera Specialization

Claude-launcher is optimized for Elm and Lamdera projects:

• Compilation Validation: Phase CTOs run validation commands defined in config.json
• Test-Driven Development: When lamdera-program-test is detected, agents follow TDD practices
• Test Execution: Configurable test commands based on your project
• Smart Error Handling: CTOs analyze compilation and test failures to create fix tasks
• Tool Integration: Pre-configured commands for elm-i18n and other Elm tools

Example: Using elm-i18n Commands

When --init-lamdera is used, the configuration includes elm-i18n commands:

"commands": [
  {
    "description": "Add internationalization keys",
    "pattern": "elm-i18n add --fr \"French text\" --en \"English text\" KEY_NAME",
    "use_instead_of": "editing src/I18n.elm directly"
  },
  {
    "description": "Add function-based translations",
    "pattern": "elm-i18n add-fn --type-sig \"Int -> String\" --en \"\\n -> ...\" --fr \"\\n -> ...\" functionName",
    "use_instead_of": "editing src/I18n.elm for parameterized translations"
  }
]

With these commands configured, agents will automatically use elm-i18n commands instead of manually editing the I18n.elm file, ensuring consistent formatting and preventing merge conflicts.

Phase CTO Behavior

When all tasks in a phase are complete but the phase status is still TODO, running claude-launcher will:

1. Detect that all steps are DONE
2. Spawn a dedicated Phase CTO agent
3. The Phase CTO will:
   • Review all completed tasks in the phase
   • Run validation commands from config.json
   • Based on results:
     • No errors: Mark phase DONE and proceed to next phase
     • Few errors (1-5): Fix them, mark phase DONE, proceed
     • Many errors (6+): Create a remediation phase with fix tasks
   • Add comprehensive phase summary with test results
   • Call claude-launcher to start the next phase

This ensures code quality and proper phase review before proceeding.

Best Practices

1. Task Independence: Ensure tasks in the same phase don't modify the same files
2. Clear Prompts: Provide detailed instructions in each task prompt
3. Limit Scope: Each task should be completable independently
4. Max 10 tasks: The tool limits you to 10 simultaneous tasks to prevent system overload

How it Works

1. Captures the current working directory
2. For each task:
   • Creates a temporary prompt file with instructions
   • Generates an AppleScript command
   • Opens a new iTerm tab
   • Runs Claude with the prompt
   • Automatically removes the prompt file after execution
3. Each Claude instance works independently and updates todos.json when complete

Example

Initialize and plan a new Lamdera app:

claude-launcher --init
claude-launcher --create-task "Build a Lamdera property management app with tenant portals and real-time notifications"
claude-launcher  # Auto-launches Phase 1 tasks in parallel

For Test-Driven Development with lamdera-program-test:

claude-launcher --create-task "Add user authentication with TDD using lamdera-program-test"
claude-launcher --step-by-step  # Runs tests first, then implementation

For sequential execution (useful for debugging):

claude-launcher --step-by-step  # Runs Phase 1, Step 1A
# After 1A completes, it automatically runs 1B, then 1C, etc.

Limitations

• macOS only (uses AppleScript)
• Requires iTerm2 (not Terminal.app)
• Maximum of 10 concurrent tasks

Contributing

Pull requests are welcome! Please feel free to submit issues or enhancement requests.

Running Tests

Important: Tests may fail intermittently when run in parallel due to race conditions with directory changes. This is a known issue.

If you see random test failures like:

• No such file or directory
• Failed to load config
• Tests that pass sometimes and fail other times

Run tests single-threaded to ensure they pass consistently:

cargo test -- --test-threads=1

This forces tests to run sequentially, preventing conflicts when multiple tests change the current directory simultaneously. The failures are not bugs in the code, but rather a limitation of the test setup.

License

This project is open source and available under the MIT License.