Claudio

A CLI/TUI tool for running multiple AI coding agents (Claude Code or Codex) simultaneously on a single project using git worktrees.

Overview

Claudio enables parallel AI-assisted development by orchestrating multiple Claude Code or Codex 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

Core Orchestration

Parallel Instances - Run multiple AI backend 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
Task Chaining - Define dependencies between tasks with --depends-on

Planning Modes

Plan Mode - Have the AI backend analyze your codebase and generate a structured task plan
UltraPlan Mode - Hierarchical 4-phase planning with automatic parallel execution
Multi-Pass Planning - Three competing strategies evaluate and select the best approach
TripleShot Mode - Spawn 3 parallel attempts per task, then judge selects the best
Adversarial Review - Iterative implementation with critical reviewer feedback loops

Workflow Automation

PR Automation - AI-generated pull requests with smart reviewer assignment
Cost Tracking - Monitor token usage and API costs with configurable limits
Session Recovery - Resume sessions after disconnection
Structured Logging - JSON logs with filtering, rotation, and export capabilities
Color Themes - 14 built-in themes plus custom theme support
Plan Validation - Validate ultraplan JSON files before execution

Requirements

Go 1.21+
Git
tmux
Claude Code or Codex 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

# Ensure Go's bin directory is in your PATH
export PATH="$PATH:$HOME/go/bin"

To make this permanent, add the export line to your shell profile (~/.bashrc, ~/.zshrc, etc.).

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

Core Commands

Command	Description
`claudio init`	Initialize Claudio in the current git repository
`claudio start [name]`	Start a new session and launch the TUI
`claudio add "task"`	Add a new instance with the given task
`claudio add "task" -d "dep1,dep2"`	Add instance with dependencies (task chaining)
`claudio status`	Show current session status
`claudio stop`	Stop all instances and end the session
`claudio pr <instance-id>`	Create a pull request for an instance
`claudio cleanup`	Clean up stale worktrees, branches, and tmux sessions

Planning Commands

Command	Description
`claudio plan "objective"`	Generate a structured task plan from an objective
`claudio ultraplan "objective"`	4-phase hierarchical planning with parallel execution
`claudio ultraplan --multi-pass "objective"`	Use 3 competing strategies to find the best plan

TUI Keyboard Shortcuts

Key	Action
`Tab` / `l` / `→`	Next instance
`Shift+Tab` / `h` / `←`	Previous instance
`J` / `K`	Scroll sidebar without changing selection
`a`	Add new instance
`s`	Start selected instance
`p`	Pause/resume instance
`x`	Stop instance
`d`	Toggle diff view
`c`	Toggle conflict view
`/`	Search output
`Enter`	Focus instance for input
`?`	Toggle help
`q`	Quit

TUI Command Mode

Press : to enter command mode for advanced operations:

Command	Description
`:a "task"`	Add a new instance
`:plan "objective"`	Start inline plan generation
`:ultraplan "objective"`	Start inline ultraplan workflow
`:multiplan "objective"`	Multi-pass planning (requires experimental flag)
`:tripleshot "task"`	Start tripleshot execution (aliases: `:triple`, `:3shot`)
`:adversarial-retry`	Restart stuck adversarial role
`:group create [name]`	Create a new instance group
`:group add <instance> <group>`	Add instance to a group
`:q!` or `:quit!`	Force quit with cleanup

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

~/.config/claudio/config.yaml (recommended)
./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:
  auto_focus_on_input: true
  max_output_lines: 1000
  sidebar_width: 36
  theme: default  # or: monokai, dracula, nord, claude-code, etc.

# Session settings
session:
  auto_start_on_add: true  # Auto-start instances when added via TUI

# Instance settings
instance:
  output_buffer_size: 100000
  capture_interval_ms: 100
  tmux_width: 200
  tmux_height: 50
  # Timeout settings (minutes)
  activity_timeout_minutes: 30
  completion_timeout_minutes: 60

# Branch naming convention
branch:
  prefix: claudio
  include_id: true

# Pull request settings
pr:
  draft: false
  auto_rebase: true
  use_ai: true
  auto_pr_on_stop: false

# Resource limits
resources:
  cost_warning_threshold: 5.00
  cost_limit: 0  # 0 = no limit
  show_metrics_in_sidebar: true

# UltraPlan settings
ultraplan:
  max_parallel: 3

# TripleShot settings
tripleshot:
  auto_approve: false
  adversarial: false  # Pair each implementer with a reviewer

# Adversarial review settings
adversarial:
  max_iterations: 10
  min_passing_score: 8

# Experimental features
experimental:
  intelligent_naming: false
  triple_shot: false
  inline_plan: false
  inline_ultraplan: false
  grouped_instance_view: false

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

Command	Description
`claudio config`	Show current configuration
`claudio config init`	Create a default config file
`claudio config set <key> <value>`	Set a configuration value
`claudio config path`	Show config file locations

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

Logging

Claudio includes a built-in debug logging system for troubleshooting and post-hoc analysis of sessions.

Enabling/Disabling Logging

Logging is enabled by default. Configure it via config file or environment variables:

# ~/.config/claudio/config.yaml
logging:
  enabled: true        # Enable/disable logging (default: true)
  level: info          # Log level (default: info)
  max_size_mb: 10      # Max file size before rotation (default: 10)
  max_backups: 3       # Number of backup files to keep (default: 3)

Or via environment variables:

export CLAUDIO_LOGGING_ENABLED=true
export CLAUDIO_LOGGING_LEVEL=debug

Log Levels

Level	Description
`debug`	Verbose output for detailed troubleshooting (all messages)
`info`	General operational messages (default)
`warn`	Warning conditions that may need attention
`error`	Error conditions that affect functionality

Each level includes all messages at and above its severity. For example, info includes info, warn, and error messages.

Log File Location

Logs are stored in the session directory:

.claudio/sessions/<session-id>/debug.log

Rotated backup files (if enabled):

debug.log.1 - Most recent backup
debug.log.2 - Second most recent
debug.log.3 - Third most recent (oldest)

Viewing Logs

Use the claudio logs command to view and filter logs:

# Show last 50 lines from most recent session
claudio logs

# Show all logs (no line limit)
claudio logs -n 0

# View logs from a specific session
claudio logs -s abc123

# Follow logs in real-time (like tail -f)
claudio logs -f

# Filter by minimum log level
claudio logs --level warn

# Show logs from the last hour
claudio logs --since 1h

# Search for patterns using regex
claudio logs --grep "error|failed"

# Combine filters
claudio logs --level error --since 30m --grep "instance"

Command Options

Flag	Short	Description
`--session`	`-s`	Session ID (default: most recent)
`--tail`	`-n`	Number of lines to show, 0 for all (default: 50)
`--follow`	`-f`	Follow log output in real-time
`--level`		Minimum level to show (debug/info/warn/error)
`--since`		Show logs since duration (e.g., 1h, 30m, 2h30m)
`--grep`		Filter by regex pattern

Example Log Output

Logs are stored in JSON format for machine parsing:

{"time":"2024-01-15T10:30:45.123Z","level":"INFO","msg":"session started","session_id":"abc123"}
{"time":"2024-01-15T10:30:46.456Z","level":"DEBUG","msg":"instance created","session_id":"abc123","instance_id":"def456","task":"implement auth"}
{"time":"2024-01-15T10:31:00.789Z","level":"WARN","msg":"conflict detected","session_id":"abc123","files":["src/auth.go"]}

The claudio logs command renders these with colors and formatting:

[10:30:45.123] [INFO] session started session_id=abc123
[10:30:46.456] [DEBUG] instance created session_id=abc123 instance_id=def456 task=implement auth
[10:31:00.789] [WARN] conflict detected session_id=abc123 files=["src/auth.go"]

Log Aggregation and Export

For advanced analysis, use the logging package's export utilities:

import "github.com/Iron-Ham/claudio/internal/logging"

// Aggregate all logs from a session
entries, err := logging.AggregateLogs(sessionDir)

// Filter logs
filtered := logging.FilterLogs(entries, logging.LogFilter{
    Level:      "WARN",
    InstanceID: "abc123",
    Phase:      "execution",
})

// Export to various formats
logging.ExportLogEntries(filtered, "output.json", "json")
logging.ExportLogEntries(filtered, "output.txt", "text")
logging.ExportLogEntries(filtered, "output.csv", "csv")

Troubleshooting

"not a git repository"

Claudio requires a git repository. Initialize one with:

git init

AI backend process not starting

Ensure your selected backend CLI is installed and authenticated.

Claude:

claude --version
claude auth status

Codex:

codex --version
# Authenticate via the Codex CLI per its documentation

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

Contributing

Contributions welcome! Please open an issue or PR.

Name		Name	Last commit message	Last commit date
Latest commit History 466 Commits
.claude/skills		.claude/skills
.github		.github
cmd/claudio		cmd/claudio
docs		docs
examples		examples
internal		internal
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
mkdocs.yml		mkdocs.yml
requirements-docs.txt		requirements-docs.txt

Uh oh!

Iron-Ham/claudio

Folders and files

Latest commit

History

Repository files navigation

Claudio

Overview

Documentation

Features

Core Orchestration

Planning Modes

Workflow Automation

Requirements

Installation

From Source

Verify Installation

Quick Start

Usage

Core Commands

Planning Commands

TUI Keyboard Shortcuts

TUI Command Mode

How It Works

Architecture

Worktrees

Shared Context

Project Structure

Configuration

Config File Locations

Creating a Config File

Configuration Options

Environment Variables

Config Commands

Development

Building

Running Tests

Project Layout

Logging

Enabling/Disabling Logging

Log Levels

Log File Location

Viewing Logs

Command Options

Example Log Output

Log Aggregation and Export

Troubleshooting

"not a git repository"

AI backend process not starting

Worktree conflicts

Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 31

Sponsor this project

Uh oh!

Packages 0

Languages

Packages