claudio

Claudio

A CLI/TUI tool for running multiple Claude Code instances simultaneously on a single project using git worktrees.

Overview

Claudio enables parallel AI-assisted development by orchestrating multiple Claude Code instances, each working in isolated git worktrees. A central orchestrator coordinates the work, tracks what each instance is doing, and helps prevent conflicts.

Documentation

Full documentation is available here →

• User Guide - Comprehensive documentation
• Tutorials - Step-by-step workflows
• CLI Reference - All commands
• Configuration - All options
• FAQ - Common questions

Features

• Parallel Instances - Run multiple Claude Code processes simultaneously
• Worktree Isolation - Each instance works in its own git worktree/branch
• TUI Dashboard - Real-time view of all instances with output streaming
• Shared Context - Instances can see what others are working on via auto-generated context files
• Process Control - Start, pause, resume, and stop instances
• Conflict Detection - Detect when instances modify the same files
• PR Automation - AI-generated pull requests with smart reviewer assignment
• Cost Tracking - Monitor token usage and API costs
• Session Recovery - Resume sessions after disconnection

Requirements

• Go 1.21+
• Git
• tmux
• Claude Code CLI installed and authenticated
• GitHub CLI (optional, for PR creation)

Installation

From Source

# Clone the repository
git clone https://github.com/Iron-Ham/claudio.git
cd claudio

# Build
go build -o claudio ./cmd/claudio

# Install to your PATH (optional)
go install ./cmd/claudio

Verify Installation

claudio --help

Quick Start

# Navigate to your project (must be a git repository)
cd your-project

# Initialize Claudio
claudio init

# Start a session (launches the TUI)
claudio start my-feature

# Or add instances directly from CLI
claudio add "Implement user authentication API"
claudio add "Write unit tests for auth module"
claudio add "Update API documentation"

Usage

Commands

TUI Keyboard Shortcuts

How It Works

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         TUI Layer                           │
│  (Bubbletea - renders state, handles keyboard input)        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Orchestrator                           │
│  - Manages session state                                    │
│  - Updates shared context                                   │
│  - Coordinates instances                                    │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   Instance 1    │ │   Instance 2    │ │   Instance 3    │
│   (worktree)    │ │   (worktree)    │ │   (worktree)    │
│  claude process │ │  claude process │ │  claude process │
└─────────────────┘ └─────────────────┘ └─────────────────┘

Worktrees

Each Claude instance runs in its own git worktree, providing:

• Isolation: Instances can modify files without affecting each other
• Parallel branches: Each instance works on its own branch
• Easy cleanup: Worktrees can be removed without losing the main repo

Worktrees are created in .claudio/worktrees/<instance-id>/ with branches named <prefix>/<instance-id>-<task-slug> (the prefix and whether to include the instance ID are configurable).

Shared Context

Claudio generates a context.md file that's injected into each worktree, containing:

• What each instance is working on
• Current status of all instances
• Files being modified
• Coordination notes

This helps Claude instances be aware of parallel work and avoid conflicts.

Project Structure

.claudio/
├── session.json          # Current session state
├── context.md            # Shared context file
└── worktrees/
    ├── abc123/           # Instance 1 worktree
    ├── def456/           # Instance 2 worktree
    └── ...

Configuration

Claudio can be configured via a YAML config file or environment variables.

Config File Locations

Claudio searches for config files in this order:

1. ~/.config/claudio/config.yaml (recommended)
2. ./config.yaml (current directory)

Creating a Config File

# Create a config file with defaults and comments
claudio config init

# Or view current configuration
claudio config

# Set individual values
claudio config set completion.default_action auto_pr
claudio config set tui.auto_focus_on_input false

Configuration Options

# Claudio Configuration
# ~/.config/claudio/config.yaml

# Action when an instance completes its task
# Options: prompt, keep_branch, merge_staging, merge_main, auto_pr
completion:
  default_action: prompt

# TUI (terminal user interface) settings
tui:
  # Automatically focus new instances for input
  auto_focus_on_input: true
  # Maximum number of output lines to display per instance
  max_output_lines: 1000

# Instance settings (advanced)
instance:
  # Output buffer size in bytes (default: 100KB)
  output_buffer_size: 100000
  # How often to capture output from tmux in milliseconds
  capture_interval_ms: 100
  # tmux pane dimensions
  tmux_width: 200
  tmux_height: 50

# Branch naming convention
branch:
  # Prefix for branch names (default: "claudio")
  # Examples: "claudio", "Iron-Ham", "feature"
  prefix: claudio
  # Include instance ID in branch names (default: true)
  # When true: <prefix>/<id>-<slug> (e.g., claudio/abc123-fix-bug)
  # When false: <prefix>/<slug> (e.g., claudio/fix-bug)
  include_id: true

Environment Variables

All config options can be set via environment variables with the CLAUDIO_ prefix. Use underscores instead of dots for nested keys:

export CLAUDIO_COMPLETION_DEFAULT_ACTION=auto_pr
export CLAUDIO_TUI_MAX_OUTPUT_LINES=2000
export CLAUDIO_BRANCH_PREFIX=Iron-Ham
export CLAUDIO_BRANCH_INCLUDE_ID=false

Config Commands

Development

Building

go build ./cmd/claudio

Running Tests

go test ./...

Project Layout

claudio/
├── cmd/claudio/          # Entry point
├── internal/
│   ├── cmd/              # CLI commands (Cobra)
│   ├── orchestrator/     # Session & coordination
│   ├── instance/         # Process management
│   ├── worktree/         # Git worktree operations
│   └── tui/              # Terminal UI (Bubbletea)
└── go.mod

Troubleshooting

"not a git repository"

Claudio requires a git repository. Initialize one with:

git init

Claude process not starting

Ensure Claude Code CLI is installed and authenticated:

claude --version
claude auth status

Worktree conflicts

If you encounter worktree issues, you can manually clean up:

# List worktrees
git worktree list

# Remove a worktree
git worktree remove .claudio/worktrees/<id>

# Prune stale worktree references
git worktree prune

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.