ccmux

A streamlined terminal-UI for juggling concurrent Claude Code sessions.

Features

• Visual sidebar — see all sessions at a glance; red highlights tell you instantly when Claude needs your attention
• CLI session management — create, list, activate, remove sessions from the terminal
• Git worktree isolation — spin up duplicate sessions on isolated branches; use ccmux.toml files to add additional steps when spinning up worktrees, such as setting up untracked build dependencies

Prerequisites

Before installing ccmux, make sure you have:

1. tmux — terminal multiplexer

   # Ubuntu/Debian
   sudo apt install tmux
   # macOS
   brew install tmux
   

2. Claude Code — Anthropic's CLI for Claude

   npm install -g @anthropic-ai/claude-code
   

   See Claude Code documentation for details.

Installation

# Recommended
pipx install ccmux

# Or, if you don't use pipx
pip install ccmux

Quick Start

ccmux             # auto-creates a session for the current directory or attaches to an existing one
ccmux new         # create a new session from the current directory's repo

Commands

Worktree Configuration

Drop a ccmux.toml in your repo root to run commands after worktree creation:

[worktree]
post_create = [
    "ln -s $CCMUX_REPO_ROOT/node_modules $CCMUX_INSTANCE_PATH/node_modules",
    "cp $CCMUX_REPO_ROOT/.env $CCMUX_INSTANCE_PATH/.env",
]

Commands run inside the new worktree with these environment variables:

Contributing

git clone git@github.com:TheHumbleTransistor/ccmux.git
cd ccmux
pip install -e ".[dev]"
pytest tests/ -v

PRs welcome — open an issue first for large changes.

License

MIT — see LICENSE