Getting started

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)

Homebrew

brew install epilande/tap/ccmux
ccmux setup

From Source

Requires Bun.

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 <name> to install for a specific agent even if it isn’t detected.

Shell Completions

ccmux completion <shell> 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:
Terminal window
```
ccmux
```
Navigate with j/k, press Enter to switch to a session

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:

bind-key C-p run-shell -C 'display-popup -E -w 80% -h 75% "ccmux --client-tty #{client_tty}"'

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