Skip to content

User Guide

Welcome to the Claudio User Guide. This documentation covers everything you need to know to effectively use Claudio for parallel AI-assisted development.

What is Claudio?

Claudio is a CLI/TUI tool that orchestrates multiple AI backend instances (Claude Code or Codex) simultaneously on a single project. It uses Git worktrees to isolate each instance's work, preventing conflicts while enabling truly parallel development.

Guides

Getting Started

Install Claudio and run your first parallel development session. Learn the basic workflow from initialization to creating pull requests.

Instance Management

Deep dive into instance lifecycle, states, and management. Understand how instances work in isolation and how to coordinate them effectively.

TUI Navigation

Master the terminal UI with keyboard shortcuts, views, and panels. Learn to efficiently navigate output, manage instances, and use search.

Configuration

Customize Claudio's behavior through config files and environment variables. Set up branch naming, PR templates, cost limits, and more.

PR Creation

Create polished pull requests with AI-generated descriptions, automatic rebasing, and smart reviewer assignment.

Task Chaining

Define dependencies between tasks to control execution order. Build complex workflows with parallel and sequential phases.

Plan Mode

Generate structured task plans from high-level objectives. Create execution plans that can be saved as JSON for Ultra-Plan or tracked as GitHub Issues.

Ultra-Plan Mode

Orchestrate complex tasks with intelligent planning. Let the AI backend analyze your codebase, create an execution plan, and coordinate parallel task execution automatically.

TripleShot Mode

Run three parallel implementations and let a judge select the best. Ideal for tasks with multiple valid approaches or when optimal solution is unclear. Access via :tripleshot command in the TUI. Can be combined with adversarial review for higher quality results.

Adversarial Review

Iterative implementation with critical reviewer feedback. The implementer and reviewer loop until the code meets quality thresholds (score >= 8/10). Includes stuck instance detection and :adversarial-retry recovery command.

Inline Planning (Experimental)

Start Plan and UltraPlan workflows directly from the standard TUI. Create plans, organize tasks into visual groups, and execute them without leaving your session.

Core Concepts

Instances

An instance is an AI backend process working on a specific task. Each instance runs independently and can be started, paused, resumed, or stopped.

Worktrees

Each instance works in its own Git worktree - a separate working directory linked to your repository. This provides complete file isolation between instances.

Sessions

A session groups multiple instances together. Sessions persist across restarts and can be recovered if the TUI is closed while instances are running.

Shared Context

Claudio generates context files that inform each instance about what others are working on, helping coordinate parallel work and avoid conflicts.

Typical Workflow

1. Initialize        claudio init
2. Start session     claudio start feature-work
3. Add instances     Press 'a' → describe tasks
4. Monitor           Watch output, check diffs
5. Create PRs        Press 'x' → create PR
6. Cleanup           claudio cleanup

Need Help?