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:

Changes to the directory where you ran the command
Reads the .claude-launcher/todos.json file in that directory
Executes the assigned task
Updates .claude-launcher/todos.json to mark the task as complete with a comment
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

Initialize Project
```
claude-launcher --init
```

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
  }
}

Create Task Plan

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

Execute with Worktrees

claude-launcher  # Auto mode with worktrees

Monitor Progress
```
claude-launcher --list-worktrees
```
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

Clone this repository:

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

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

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.

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.

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:

Detect that all steps are DONE
Spawn a dedicated Phase CTO agent
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

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

How it Works

Captures the current working directory
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
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.

agents-launcher 0.3.1

Claude Launcher

What it does

Automatic Task Detection

Step-by-Step Mode

Git Worktree Integration

Features

Configuration

Configuration Options

Usage

Run with Worktrees

List Active Worktrees

Clean Up Worktrees

Workflow Example

Benefits

Troubleshooting

Prerequisites

Installation

From Source

Manual Build

Usage

Commands

Workflow

Directory Structure

config.json

Agent Commands

todos.json

Elm/Lamdera Specialization

Example: Using elm-i18n Commands

Phase CTO Behavior

Best Practices

How it Works

Example

Limitations

Contributing

Running Tests

License