cctakt

A TUI orchestrator for managing multiple Claude Code agents in parallel using Git Worktree

cctakt is a Rust-based TUI application that manages multiple Claude Code agents via Git Worktree and executes coding tasks in parallel.

Features

• Parallel Execution: Leverage Git Worktree to run multiple tasks simultaneously
• Conductor Mode: Launch Claude Code as a "conductor" in the main repository to orchestrate workers via plan.json
• Worker Management: Monitor and interact with each worker's PTY output in real-time
• Auto Review: Display diffs when workers complete and support merge decisions
• GitHub Issues Integration: Auto-generate workers from issues with suggested branch names
• Plan Feature: Structured task management via .cctakt/plan.json
• Themes: 6 color themes (Cyberpunk, Monokai, Dracula, Nord, Arctic Aurora, Minimal)

Requirements

• Rust 2024 Edition
• Claude Code CLI installed
• Git

Installation

cargo install cctakt

Building from Source

git clone https://github.com/taiki3/cctakt.git
cd cctakt
cargo install --path .

Usage

Quick Start

cctakt init   # Initial setup
cctakt        # Launch TUI

Workflow

sequenceDiagram
    actor User
    participant Conductor
    participant cctakt
    participant Worker

    User->>Conductor: Request task
    Conductor->>cctakt: add_task
    cctakt->>Worker: Create worktree & launch
    Worker->>Worker: Implement & commit
    Worker-->>cctakt: Complete
    cctakt->>User: Review screen
    User->>cctakt: Approve merge
    cctakt->>cctakt: Merge to main

1. Give Instructions to the Conductor

Give tasks to the conductor Claude Code in the left pane using natural language:

Implement authentication. Create login and logout API endpoints.

The conductor uses the MCP tool add_task to create workers.

2. Workers Implement

Workers appear in the right pane and automatically start implementation.

• Work in dedicated Git Worktree (keeps main clean)
• Auto-commit on completion

3. Review & Merge

After a worker completes, a review screen with diff is displayed:

• j/k to scroll
• Enter or m to approve merge
• q to cancel

A build check runs automatically after merge.

Key Bindings

Global

Navigation Mode

Input Mode

Review Mode

Theme Picker

Conductor Mode and plan.json

cctakt supports "Conductor Mode". Launch Claude Code in the main repository and write plans to .cctakt/plan.json, and cctakt will automatically generate and manage workers.

plan.json Structure

{
  "version": 1,
  "created_at": 1700000000,
  "description": "Task description",
  "tasks": [
    {
      "id": "worker-1",
      "action": {
        "type": "create_worker",
        "branch": "feat/example",
        "task_description": "Detailed implementation requirements",
        "base_branch": "main"
      },
      "status": "pending"
    },
    {
      "id": "review-1",
      "action": {
        "type": "request_review",
        "branch": "feat/example",
        "after_task": "worker-1"
      },
      "status": "pending"
    }
  ]
}

Supported Actions

Task Status

Task Results

A result field is set upon task completion:

{
  "result": {
    "commits": ["abc1234 feat: add feature"],
    "pr_number": 42,
    "pr_url": "https://github.com/owner/repo/pull/42"
  }
}

MCP Server Integration

cctakt also operates as a Model Context Protocol (MCP) server, allowing the conductor Claude Code to manage tasks through cctakt instead of directly manipulating plan.json. This avoids file conflicts and race conditions.

Setup

Running cctakt init automatically adds MCP server configuration to .claude/settings.json:

{
  "mcpServers": {
    "cctakt": {
      "command": "/path/to/cctakt",
      "args": ["mcp"]
    }
  }
}

Available Tools

add_task Parameters

Usage from Conductor

The conductor Claude Code can add tasks using MCP tools as follows:

Using add_task:
- id: "impl-auth"
- branch: "feat/auth"
- description: "Implement login functionality..."

Once a task is added, cctakt automatically detects it and launches the worker.

Configuration File

Place .cctakt.toml in the project root to customize settings. The cctakt init command generates a default configuration file.

# Worktree storage location (default: .worktrees)
worktree_dir = ".worktrees"

# Branch name prefix (default: cctakt)
branch_prefix = "cctakt"

# Color theme: cyberpunk, monokai, dracula, nord, arctic, minimal
# Default: cyberpunk
theme = "cyberpunk"

[github]
# Auto-fetch issues (default: false)
auto_fetch_issues = false
# Repository (owner/repo format)
repository = "owner/repo"
# Filter labels
labels = ["cctakt", "good first issue"]

[anthropic]
# Anthropic API key (can also be set via ANTHROPIC_API_KEY env var)
# api_key = "sk-ant-..."
# Model to use (default: claude-sonnet-4-20250514)
model = "claude-sonnet-4-20250514"
# Max tokens (default: 1024)
max_tokens = 1024
# Auto-generate PR description (default: true)
auto_generate_pr_description = true

[keybindings]
# Default values shown
new_agent = "ctrl+t"
close_agent = "ctrl+w"
next_tab = "tab"
prev_tab = "shift+tab"
quit = "ctrl+q"

All configuration options are optional. Default values are used for unspecified items.

Tech Stack

Architecture

cctakt (TUI)
├── Conductor Claude Code (main repository)
│   └── Writes plan to .cctakt/plan.json
│
└── Worker Claude Code (each worktree)
    └── Executes actual tasks

Module Structure

License

GPL-3.0