Run all your AI coding agents (Claude Code, Codex, Cursor, ...) in tmux: jump to the one that needs you, spawn them into worktrees, and hand work between them
When running multiple AI coding agent sessions across tmux panes, it's hard to keep track of which session is idle, which is waiting for permission, and which pane to switch to. ccmux solves this with a background daemon that monitors session activity and an interactive TUI that shows live session states at a glance.
It works with your existing tmux workflow. You don't change how you launch or run your agents; ccmux discovers what's already running in your panes, so as long as you're in tmux with a supported agent, it just works.
Built-in support for: Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity, Copilot, Gemini CLI, plus custom agent definitions via config.
✨ Features
🎯 Live Session States: Every agent tracked as idle, working, or waiting (permission / plan approval / question), flagged the moment one needs you
🧩 Multi-Agent: Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity, Copilot, Gemini CLI, plus custom agents via config
🔄 Real-Time: Background daemon streams state changes instantly over SSE, no polling, no refresh
👁️ Live Preview: Split-pane view of the selected session's pane content
⚡ Act in Place: Tab into the preview to approve, answer, or type, keys go straight to that pane
🔔 Actionable Notifications: Approve, deny, or reply to a waiting agent straight from the desktop notification
🪟 Sidebar Mode: Compact always-visible session rail docked beside your working panes
🔍 Fuzzy Search: Fuzzy-match sessions by project, branch, or path; substring-match any recent prompt, captured pane content, and on-demand live transcripts
📂 Session Grouping: Collapsible project groups with reordering and pinning
🌿 Git & PR Aware: Branch and worktree detection, open PRs with live CI and review status
🌱 Worktree Workflow: Spawn or fork sessions into fresh git worktrees, move uncommitted changes out of a dirty checkout, and prune leftovers from the Worktrees panel
📝 Diff Review: Press d to review a session's working-tree diff with hunk, right in the pane, or D for everything the branch changed since it forked
🤖 Background Agents & Subagents: Claude Code background agents get rows too; running subagents show as agents with a live list in the preview
🎛️ Session Control: Spawn, fork, kill, and restart sessions from the TUI; ccmux invoke for scripted one-shot agent turns
🤝 Session Handoff: Send a session's last response to another agent, from the CLI, the row menu, or agent-to-agent via the bundled relay skill
⌨️ Keyboard-First, Mouse-Friendly: Vim keys and number jumps, plus click-to-switch and right-click context actions
📦 Installation
Prerequisites
tmux with active sessions running AI coding agents
git 2.31 or newer (for branch and worktree detection; ccmux still works without it, just without that info)
git clone https://github.com/epilande/ccmux.git
cd ccmux
bun install
bun link
ccmux setup
ccmux setup installs agent hooks for authoritative session matching. ccmux works without it, but it's recommended; see Session Matching with Hooks. Bare ccmux setup only configures agents whose executable is found on PATH; use ccmux setup --agent to install for a specific agent even if it isn't detected.
Shell Completions
ccmux completion prints a completion script for zsh, bash, or fish. It completes commands and flags, and asks the running daemon for live values: session ids and %pane ids wherever a command takes one, agent names, invocation ids, config keys and their values. Directory flags such as --cwd fall through to the shell's own path completion.
# zsh (~/.zshrc, after compinit)
eval "$(ccmux completion zsh)"
bash (~/.bashrc)
eval "$(ccmux completion bash)"
fish
ccmux completion fish > ~/.config/fish/completions/ccmux.fish
The zsh eval has to come after compinit, since the script registers itself with compdef. A file in fpath sidesteps that and avoids running ccmux at every shell start: ccmux completion zsh > ~/.zfunc/_ccmux with fpath=(~/.zfunc $fpath) before compinit. The Homebrew formula installs completions for all three shells.
🚀 Quick Start
Start your AI coding sessions in tmux panes as usual
Launch the picker:
ccmux
Navigate with j/k, press Enter to switch to a session
[!TIP]
Bind a tmux key so you can pop ccmux open from anywhere (add to ~/.tmux.conf):
>
> # Prefix + C-p: open ccmux in a centered popup
> bind-key C-p display-popup -E -w 80% -h 75% "ccmux"
>
> # Or skip the prefix entirely (Alt+p from any pane)
> bind-key -n M-p display-popup -E -w 80% -h 75% "ccmux"
>
> With the binding above, ccmux works out on its own which terminal opened the popup, so picking a session switches that terminal and leaves any other attached client where it was. The picker exits after selection, so the popup closes itself and drops you straight into that pane. (display-popup needs tmux 3.2+.)
> Hand ccmux the client explicitly if you attach two terminals to the SAME tmux session, since nothing inside the popup can tell them apart, or if your binding opens the popup on a session other than the one the pressing terminal is looking at:
> The run-shell -C wrapper is what makes #{client_tty} expand, since display-popup never expands its own command. The -e "CCMUX_CLIENT_TTY=#{client_tty}" form documented previously still works, on tmux 3.3+.
