Metadata-Version: 2.5
Name: cctmux
Version: 0.6.1
Summary: Launch Claude Code inside tmux with session management
Project-URL: Homepage, https://github.com/paulrobello/cctmux
Project-URL: Documentation, https://github.com/paulrobello/cctmux/blob/main/README.md
Project-URL: Source, https://github.com/paulrobello/cctmux
Project-URL: Issues, https://github.com/paulrobello/cctmux/issues
Author-email: Paul Robello <probello@gmail.com>
Maintainer-email: Paul Robello <probello@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Paul Robello
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: claude,claude-code,cli,multiplexer,session-management,terminal,tmux
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: pydantic>=2.14.3
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.29.1
Requires-Dist: xdg-base-dirs>=6.1.0
Description-Content-Type: text/markdown

# cctmux

Launch Claude Code inside tmux with session management, real-time monitoring, and pane awareness.

![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue)
![Runs on Linux | MacOS](https://img.shields.io/badge/runs%20on-Linux%20%7C%20MacOS-blue)
![Arch x86-64 | ARM | AppleSilicon](https://img.shields.io/badge/arch-x86--64%20%7C%20ARM%20%7C%20AppleSilicon-blue)
![License MIT](https://img.shields.io/badge/license-MIT-green)

[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/probello3)

![cctmux screenshot](https://raw.githubusercontent.com/paulrobello/cctmux/main/screenshot.png)

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Tools](#cli-tools)
- [Layouts](#layouts)
- [Monitoring Tools](#monitoring-tools)
  - [Git Monitor](#git-monitor-cctmux-git)
  - [Ralph Monitor](#ralph-monitor-cctmux-ralph)
- [Configuration](#configuration)
- [Team Mode](#team-mode)
- [Claude Skill](#claude-skill)
- [Environment Variables](#environment-variables)
- [Requirements](#requirements)
- [Development](#development)
- [Documentation](#documentation)
- [License](#license)

## Features

- **Session Management**: Create and attach to tmux sessions named after your project folder
- **Predefined Layouts**: Choose from 10 layouts including monitoring-focused arrangements
- **Real-time Monitors**: Track tasks, session events, subagents, usage statistics, and Ralph Loop progress
- **Ralph Loop Automation**: Automated iterative Claude Code execution with task tracking and cost monitoring
- **Claude Awareness**: Environment variables (`$CCTMUX_SESSION`, `$CCTMUX_PROJECT_DIR`) for Claude integration
- **Session History**: Track recent sessions with fzf integration for quick switching
- **Configuration Presets**: Quick access to minimal, verbose, or debug configurations
- **Status Bar**: Optional tmux status bar showing git branch and project info
- **Claude Skill**: Enables Claude to manage tmux panes for dev servers, watchers, etc.
- **pitmux**: Launch the `pi` coding agent in tmux sessions with the same layout/config support
- **cdxtmux**: Launch the `codex` CLI in tmux sessions, with codex `resume` subcommand support and yolo mode
- **gemtmux**: Launch the `gemini` CLI in tmux sessions, with `--resume latest` and `--yolo` support
- **Dry Run Mode**: Preview tmux commands without executing

```mermaid
graph TB
    subgraph "cctmux CLI Tools"
        Main[cctmux]
        Pitmux[pitmux]
        Cdxtmux[cdxtmux]
        Gemtmux[gemtmux]
        Tasks[cctmux-tasks]
        Session[cctmux-session]
        Agents[cctmux-agents]
        Activity[cctmux-activity]
        GitMon[cctmux-git]
        Ralph[cctmux-ralph]
    end

    subgraph "Tmux Integration"
        TmuxSession[Tmux Session]
        Panes[Layout Panes]
    end

    subgraph "Claude Code"
        Claude[Claude Code CLI]
        TaskFiles[Task Files]
        SessionFiles[Session JSONL]
        StatsCache[Stats Cache]
        RalphState[Ralph State JSON]
    end

    subgraph "External"
        GitRepo[Git Repository]
    end

    Main --> TmuxSession
    Pitmux --> TmuxSession
    TmuxSession --> Panes
    Panes --> Claude

    Tasks --> TaskFiles
    Session --> SessionFiles
    Agents --> SessionFiles
    Activity --> StatsCache
    GitMon --> GitRepo
    Ralph --> RalphState
    Ralph --> Claude

    style Main fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
    style Pitmux fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
    style Tasks fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
    style Session fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
    style Agents fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
    style Activity fill:#880e4f,stroke:#c2185b,stroke-width:2px,color:#ffffff
    style GitMon fill:#004d40,stroke:#00897b,stroke-width:2px,color:#ffffff
    style Ralph fill:#bf360c,stroke:#ff6d00,stroke-width:2px,color:#ffffff
    style TmuxSession fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
    style Panes fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
    style Claude fill:#1a237e,stroke:#3f51b5,stroke-width:2px,color:#ffffff
    style TaskFiles fill:#1a237e,stroke:#3f51b5,stroke-width:2px,color:#ffffff
    style SessionFiles fill:#1a237e,stroke:#3f51b5,stroke-width:2px,color:#ffffff
    style StatsCache fill:#1a237e,stroke:#3f51b5,stroke-width:2px,color:#ffffff
    style RalphState fill:#1a237e,stroke:#3f51b5,stroke-width:2px,color:#ffffff
    style GitRepo fill:#004d40,stroke:#00897b,stroke-width:2px,color:#ffffff
```

## Installation

### Using uv (Recommended)

```bash
uv tool install cctmux
```

### From GitHub

```bash
uv tool install git+https://github.com/paulrobello/cctmux.git
```

### Using pip

```bash
pip install cctmux
```

### From Source

```bash
git clone https://github.com/paulrobello/cctmux.git
cd cctmux
uv sync
uv run cctmux --help
```

## Quick Start

```bash
# Launch Claude Code in tmux for current project
cd ~/my-project
cctmux

# Start with monitoring layout (Claude + session monitor + task monitor)
cctmux -l cc-mon

# Select from recent sessions
cctmux --recent

# Preview commands without executing
cctmux --dry-run

# Start a Ralph Loop with monitoring layout
cctmux -l ralph
```

## CLI Tools

cctmux provides seven CLI commands for Claude Code, plus `pitmux` for the pi
coding agent, `cdxtmux` for the codex CLI, and `gemtmux` for the gemini CLI:

| Command | Purpose |
|---------|---------|
| `cctmux` | Launch Claude Code in a tmux session |
| `pitmux` | Launch the pi coding agent in a tmux session |
| `cdxtmux` | Launch the codex CLI in a tmux session |
| `gemtmux` | Launch the gemini CLI in a tmux session |
| `cctmux-tasks` | Monitor Claude Code tasks in real-time |
| `cctmux-session` | Monitor session events and statistics |
| `cctmux-agents` | Monitor subagent activity |
| `cctmux-activity` | Display usage statistics dashboard |
| `cctmux-git` | Monitor git repository status in real-time |
| `cctmux-ralph` | Ralph Loop automation (start, monitor, stop, cancel, status, init) |

### cctmux

Main session launcher.

```bash
cctmux [OPTIONS]
```

| Option | Short | Description |
|--------|-------|-------------|
| `--layout` | `-l` | Tmux layout (default, editor, monitor, triple, cc-mon, full-monitor, dashboard, ralph, ralph-full, git-mon) |
| `--resume` | `-r` | Append `--resume` to claude invocation to continue last conversation |
| `--continue` | `-c` | Append `--continue` to claude invocation to continue most recent conversation |
| `--yolo` | `-y` | Append `--dangerously-skip-permissions` to claude invocation |
| `--claude-args` | `-a` | Arguments to pass to claude command |
| `--recent` | `-R` | Select from recent sessions using fzf |
| `--status-bar` | `-s` | Enable status bar with git/project info |
| `--task-list-id` | `-T` | Set `CLAUDE_CODE_TASK_LIST_ID` env var |
| `--dry-run` | `-n` | Preview commands without executing |
| `--config` | `-C` | Custom config file path |
| `--dump-config` | | Output current configuration |
| `--debug` | `-D` | Enable debug output |
| `--verbose` | `-v` | Increase verbosity (stackable) |

**Subcommands:**

```bash
cctmux init-config    # Create default configuration file
cctmux install-skill  # Install the cc-tmux skill for Claude
```

### pitmux

Launch the pi coding agent in a tmux session. Mirrors `cctmux`'s core flags
(layout, status-bar, dry-run, `-c`/`-r`, config) and uses a configurable
session prefix (`pi-` by default) so both tools can run simultaneously for
the same project.

```bash
pitmux                          # Launch pi for the current project
pitmux -c                       # Continue the previous pi session
pitmux -r                       # Resume a pi session (select from list)
pitmux --pi-args "--model x"    # Pass arguments to pi
pitmux -l editor                # Use the editor layout
pitmux --dry-run                # Preview commands
pitmux install-skill            # Install the pi-tmux skill
pitmux init-config              # Create default configuration file
```

If no `pitmux` session exists for the project but a sibling `cctmux`,
`cdxtmux`, or `gemtmux` session does (and vice versa for the other tools),
the launcher prompts to attach to the existing session instead of creating
a new one.

See [CLI Reference](docs/CLI_REFERENCE.md#pitmux) for the full options table.

### cdxtmux

Launch the codex CLI in a tmux session. Mirrors `cctmux`'s core flags
(layout, status-bar, dry-run, `-c`/`-r`/`-y`, config) and uses a configurable
session prefix (`cdx-` by default) so all three launchers can run simultaneously
for the same project. `--continue` and `--resume` insert codex's `resume`
subcommand (`codex resume --last` or `codex resume`).

```bash
cdxtmux                              # Launch codex for the current project
cdxtmux -c                           # Continue the most recent codex session
cdxtmux -r                           # Pick a codex session to resume
cdxtmux -y                           # Skip approvals + sandbox
cdxtmux --codex-args "--model gpt-5" # Pass arguments to codex
cdxtmux -l editor                    # Use the editor layout
cdxtmux --dry-run                    # Preview commands
cdxtmux init-config                  # Create default configuration file
```

See [CLI Reference](docs/CLI_REFERENCE.md#cdxtmux) for the full options table.

### gemtmux

Launch the gemini CLI in a tmux session. Mirrors `cctmux`'s core flags
(layout, status-bar, dry-run, `-c`/`-r`/`-y`, config) and uses a configurable
session prefix (`gem-` by default) so all four launchers can run simultaneously
for the same project. Both `-c` and `-r` map to gemini's `--resume latest` since
gemini lacks a separate interactive picker.

```bash
gemtmux                                  # Launch gemini for the current project
gemtmux -c                               # Continue the most recent gemini session
gemtmux -y                               # Yolo mode (auto-accept all actions)
gemtmux --gemini-args "--model gemini-2.5-pro"  # Pass arguments to gemini
gemtmux --gemini-args "--resume 5"       # Resume a specific indexed session
gemtmux -l editor                        # Use the editor layout
gemtmux --dry-run                        # Preview commands
gemtmux init-config                      # Create default configuration file
```

See [CLI Reference](docs/CLI_REFERENCE.md#gemtmux) for the full options table.

## Layouts
| Layout | Description |
|--------|-------------|
| `default` | No initial splits (panes created on demand) |
| `editor` | 70/30 horizontal split (main + side pane) |
| `monitor` | 80/20 vertical split (main + bottom bar) |
| `triple` | Main pane with two side panes (30% right, split vertically) |
| `cc-mon` | Claude + session monitor + task monitor |
| `full-monitor` | Claude + session + tasks + activity monitors |
| `dashboard` | Large activity dashboard with session sidebar |
| `ralph` | Shell + ralph monitor side-by-side (60/40) |
| `ralph-full` | Claude + git monitor + ralph monitor + task monitor (2x2 grid) |
| `git-mon` | Claude (60%) + git status monitor (40%) |

### CC-Mon Layout

The recommended layout for monitoring Claude Code activity:

```bash
cctmux -l cc-mon
```

```
┌──────────────────┬──────────────────┐
│                  │ cctmux-session   │
│                  │      50%         │
│   Claude Code    ├──────────────────┤
│      50%         │ cctmux-tasks -g  │
│                  │      50%         │
│                  │                  │
└──────────────────┴──────────────────┘
```

## Monitoring Tools

### Task Monitor (`cctmux-tasks`)

Watch task progress with ASCII dependency visualization.

```bash
cctmux-tasks                    # Auto-detect from current project
cctmux-tasks abc123             # Monitor specific session
cctmux-tasks --list             # List available sessions
cctmux-tasks -g                 # Show only dependency graph
cctmux-tasks --preset verbose   # Use verbose preset
```

**Features:**
- ASCII dependency graph with task relationships
- Status indicators: `○` pending, `◐` in progress, `●` completed
- Progress statistics and completion percentage
- Acceptance criteria tracking from metadata
- Windowed virtual scrolling for large task lists
- Supports both `TaskCreate` directory format and `TodoWrite` todos format (`claude -p` sessions)

### Session Monitor (`cctmux-session`)

Track session events in real-time.

```bash
cctmux-session                  # Auto-detect from current project
cctmux-session abc123           # Monitor specific session
cctmux-session --list           # List available sessions
cctmux-session --no-thinking    # Hide thinking blocks
cctmux-session --preset debug   # Use debug preset
```

**Features:**
- Tool calls and results display
- Thinking block visualization
- Token usage and cost estimates
- Tool usage histogram
- Stop reason and turn duration tracking

### Subagent Monitor (`cctmux-agents`)

Monitor subagent activity across parallel tasks.

```bash
cctmux-agents                   # Auto-detect from current project
cctmux-agents abc123            # Monitor specific session
cctmux-agents --list            # List available subagents
cctmux-agents --no-activity     # Hide activity panel
cctmux-agents -M 10             # Show at most 10 agents
```

**Features:**
- Named agent display — shows assigned names (e.g., `fix-security`) instead of hash IDs
- Active and completed subagent tracking
- Token usage per agent
- Current activity display
- Aggregate statistics

### Activity Dashboard (`cctmux-activity`)

View usage statistics from Claude Code.

```bash
cctmux-activity                 # Show default dashboard
cctmux-activity --days 7        # Show 7-day heatmap
cctmux-activity --show-hourly   # Include hourly distribution
cctmux-activity --no-cost       # Hide cost estimates
```

**Features:**
- Session and message totals
- Model usage breakdown with cost estimates
- Activity heatmap visualization
- Hourly distribution chart

### Git Monitor (`cctmux-git`)

Monitor git repository status in real-time.

```bash
cctmux-git                      # Monitor current directory
cctmux-git -p /path/to/repo     # Monitor specific repo
cctmux-git --no-log             # Hide recent commits
cctmux-git --no-diff            # Hide diff stats
cctmux-git -m 20                # Show 20 recent commits
cctmux-git -M 30                # Show at most 30 files (default: 20)
cctmux-git --preset minimal     # Minimal display
cctmux-git --fetch              # Enable periodic remote fetch
cctmux-git --fetch -F 30        # Fetch every 30 seconds (default: 60s)
```

**Features:**
- Branch info with upstream tracking and ahead/behind counts
- File status display with staged, unstaged, and untracked indicators
- Recent commits log with author and relative timestamps
- Diff statistics with visual insertion/deletion bars
- Stash count display
- Configurable max display limits for files and commits (prevents panel overflow)
- Periodic remote fetch with remote commits panel (opt-in via `--fetch`)

### Ralph Monitor (`cctmux-ralph`)

Automated iterative Claude Code execution with live monitoring.

```bash
cctmux-ralph                          # Monitor a running Ralph Loop
cctmux-ralph start ralph-project.md   # Start a Ralph Loop from project file
cctmux-ralph init                     # Create a template project file
cctmux-ralph status                   # Show current Ralph Loop status
cctmux-ralph stop                     # Stop after current iteration finishes
cctmux-ralph cancel                   # Cancel an active Ralph Loop immediately
```

**Features:**
- Iteration progress and task completion tracking
- Token usage and cost estimates per iteration
- Timeline visualization of loop progress
- Completion detection via task checks, promise tags, or max iterations
- Graceful stop after current iteration or immediate cancellation
- Per-iteration timeout support (`--timeout`)
- Yolo mode (`--yolo`) to skip all permission checks

## Configuration

cctmux supports layered configuration with deep merging:

1. **User config** (`~/.config/cctmux/config.yaml`) — base settings
2. **Project config** (`.cctmux.yaml` in project dir) — shared team overrides (commit to repo)
3. **Project local config** (`.cctmux.yaml.local` in project dir) — personal overrides (gitignored)

Last value wins. Partial nested overrides (e.g., only `git_monitor.fetch_enabled`) don't wipe sibling fields. Set `ignore_parent_configs: true` in a project config to skip user config entirely.

User config file location: `~/.config/cctmux/config.yaml`

```yaml
# Main settings
default_layout: default
status_bar_enabled: false
max_history_entries: 50
default_claude_args: null
task_list_id: false

# Session monitor settings
session_monitor:
  show_thinking: true
  show_results: true
  show_progress: true
  show_cwd: false
  show_threading: false
  max_events: 50

# Task monitor settings
task_monitor:
  show_owner: true
  show_metadata: false
  show_description: true
  show_graph: true
  show_table: true
  max_tasks: 100

# Activity monitor settings
activity_monitor:
  default_days: 7
  show_heatmap: true
  show_cost: true
  show_tool_usage: true
  show_model_usage: true

# Agent monitor settings
agent_monitor:
  inactive_timeout: 300.0

# Git monitor settings
git_monitor:
  show_log: true
  show_diff: true
  show_status: true
  max_commits: 10
  poll_interval: 2.0

# Ralph monitor settings
ralph_monitor:
  show_table: true
  show_timeline: true
  show_prompt: false
  show_task_progress: true
  max_iterations_visible: 20
```

### Configuration Presets

All monitors support `--preset` for quick configuration:

| Preset | Description |
|--------|-------------|
| `minimal` | Essential info only, reduced visual noise |
| `verbose` | All information displayed |
| `debug` | Maximum detail for troubleshooting |

```bash
cctmux-session --preset minimal
cctmux-tasks --preset verbose
cctmux-activity --preset debug
cctmux-git --preset verbose
cctmux-ralph --preset verbose
```

### Create Default Config

```bash
cctmux init-config
```

## Team Mode

Launch multiple Claude Code instances as a coordinated team in a single tmux session. Each agent gets its own pane with a role-specific system prompt, and all agents communicate via the [cc2cc](https://github.com/paulrobello/cc2cc) plugin.

### Usage

```bash
# From a standalone team config file
cctmux team team.yaml

# From .cctmux.yaml (reads the team: section)
cctmux team

# Preview without executing
cctmux team team.yaml --dry-run
```

### Team Configuration

```yaml
team:
  name: my-team              # optional; defaults to project name
  shared_task_list: true     # all instances share CLAUDE_CODE_TASK_LIST_ID
  layout: grid               # "grid", "columns", or "rows"
  monitor: true              # add a cctmux-tasks monitor pane
  agents:
    - role: architect
      model: opus
      prompt: |
        You lead the team. Create tasks, review work, coordinate via cc2cc.
    - role: implementer
      model: opus
      prompt: |
        Pick up tasks and implement them.
    - role: tester
      model: sonnet
      prompt: |
        Write and run tests for completed features.
```

**Requirements:** cc2cc hub running, cc2cc plugin installed. All agents auto-subscribe to the project's cc2cc topic and share a `CLAUDE_CODE_TASK_LIST_ID` when `shared_task_list` is enabled.

**Permissions:** All team agents are launched with `--dangerously-skip-permissions` so they can operate autonomously without interactive prompts.

**Layout options:** `grid` (default) arranges panes in an N-column grid, `columns` arranges panes in equal-width columns, `rows` stacks panes top-to-bottom.

## Claude Skills

Install all bundled skills:

```bash
cctmux install-skill
```

Skills are also auto-synced on every `cctmux` invocation. The `pitmux` command auto-installs the `pi-tmux` skill to `~/.pi/agent/skills/`.

### cc-tmux

Pane management — Claude can:

- **Discover Session Context**: Access `$CCTMUX_SESSION` and `$CCTMUX_PROJECT_DIR`
- **Inspect Panes as JSON**: `cctmux panes --json` returns stable pane IDs, commands, and geometry — no tmux format-string parsing
- **Create Panes**: Split windows for dev servers, file watchers, test runners
- **Manage Processes**: Start, stop, and restart background processes
- **Navigate Panes**: Move focus between panes programmatically
- **Drive Another Claude**: Orchestrate a second Claude Code instance in another pane — `cctmux wait-idle` blocks until the remote agent finishes a turn (idle-or-heartbeat), plus reliable command submission and answering its question menus (see `references/driving-claude-panes.md`)

### cc-team-lead

Team coordination workflow for leading a `cctmux team` session. Invoke with `/cc-team-lead`. Covers:

- **Prerequisites check** — verifies cc2cc plugin is installed and hub is reachable
- **Task creation** — naming conventions, dependency ordering, example tasks
- **Team communication** — topic broadcasts, direct messages, role-based routing
- **Progress monitoring** — shared task list, monitor pane, direct check-ins
- **Issue handling** — stuck agents, merge conflicts, failing checks

### Using the Skill

Simply ask Claude to manage your development environment:

```
Start a dev server in a side pane
```

```
Set up panes for frontend server and test watcher
```

```
Run pytest in watch mode in a side pane
```

```
Restart the dev server - it crashed
```

Claude will automatically detect the cctmux session and manage panes appropriately.

### Skill Pattern

The skill follows a "create then launch" pattern using pane IDs for reliable targeting:

```bash
# Create pane and capture its ID
PANE=$(tmux split-window -d -P -F "#{pane_id}" -t "$CCTMUX_SESSION" -h -p 30)

# Launch application using pane ID
tmux send-keys -t "$PANE" "npm run dev" Enter
```

For detailed usage examples and best practices, see the [Skill Guide](docs/SKILL_GUIDE.md).

## Environment Variables

Inside a cctmux or pitmux session:

| Variable | Description |
|----------|-------------|
| `CCTMUX_SESSION` | The tmux session name |
| `CCTMUX_PROJECT_DIR` | The project directory path |
| `CLAUDE_CODE_TASK_LIST_ID` | Session name (if `--task-list-id` enabled, cctmux only) |
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Set to `1` (if `--agent-teams` enabled, cctmux only) |
| `CC2CC_SESSION_ID` | Unique ID per pane in team mode, so each agent gets its own cc2cc session file (`cctmux team` only) |

## Requirements

- **Python**: 3.13+
- **tmux**: Terminal multiplexer, 3.1+
- **Claude Code**: Claude Code CLI (`claude`)
- **pi**: Optional, pi coding agent CLI (`pi`) — required for `pitmux`
- **fzf**: Optional, for `--recent` session selection

## Development

```bash
# Clone and install
git clone https://github.com/paulrobello/cctmux.git
cd cctmux
uv sync

# Run all checks (format, lint, typecheck, test)
make checkall

# Individual commands
make fmt        # Format code
make lint       # Lint code
make typecheck  # Type check
make test       # Run tests
make upgrade    # Upgrade installed tool and reinstall skill
```

## Documentation

Full documentation is available in the `docs/` directory:

- [Quick Start Guide](docs/QUICKSTART.md) - Get started in minutes
- [Architecture](docs/ARCHITECTURE.md) - System design and data flow
- [CLI Reference](docs/CLI_REFERENCE.md) - Complete reference for all ten entry points
- [Layouts Reference](docs/LAYOUTS.md) - All ten predefined layouts with diagrams
- [Skill Guide](docs/SKILL_GUIDE.md) - Using the cc-tmux skill with Claude
- [Configuration](docs/CONFIGURATION.md) - Configuration options and presets
- [Team Mode](docs/CC2CC_TEAM.md) - Multi-agent team coordination via cc2cc

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
