Skip to main content

cctmux

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

Python 3.13+ Runs on Linux | MacOS Arch x86-64 | ARM | AppleSilicon License MIT

"Buy Me A Coffee"

cctmux screenshot

Table of Contents

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

uv tool install cctmux

From GitHub

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

Using pip

pip install cctmux

From Source

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

Quick Start

# 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.

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:

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.

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 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).

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

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

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.

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.

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.

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.

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.

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.

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

# 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
cctmux-session --preset minimal
cctmux-tasks --preset verbose
cctmux-activity --preset debug
cctmux-git --preset verbose
cctmux-ralph --preset verbose

Create Default Config

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 plugin.

Usage

# 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

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:

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:

# 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.

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

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

Metadata

Release files for cctmux 0.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cctmux 0.6.1
File Size Uploaded Provenance Actions
cctmux-0.6.1.tar.gz 131.2 kB With provenance Details for cctmux-0.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cctmux 0.6.1
File Interpreter ABI Platform Actions
cctmux-0.6.1-py3-none-any.whl Python 3 none any Details for cctmux-0.6.1-py3-none-any.whl

Total release size: 275.7 kB

Release files / cctmux-0.6.1.tar.gz

Download URL cctmux-0.6.1.tar.gz
Size 131.2 kB
Tags Source
SHA-256 checksum
How to use checksums
8b0cf20f10306d28f2b16ef0b47a59237608989feca05be3db2752689fc197c5
BLAKE2b-256 checksum
How to use checksums
9590382db93bdb6d9192ef7e09350bc92175705aeb7d3a53ff11bd57c7c9725a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / cctmux-0.6.1-py3-none-any.whl

Download URL cctmux-0.6.1-py3-none-any.whl
Size 144.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6b3594641825eeb91c67a3de747ac59611d7fcd7fa94af4814a6e7a056f7bc35
BLAKE2b-256 checksum
How to use checksums
cc6795dc10b8668677fcca3750088acc89cbd90af66f657d13d7b159f41e6df3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for cctmux 0.6.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cctmux-0.6.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page