This is the abridged developer documentation for ccmux # Getting started > Install ccmux, set up agent hooks, and open a session picker in tmux. ## Installation ### Prerequisites * [tmux](https://github.com/tmux/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 ```sh brew install epilande/tap/ccmux ccmux setup ``` ### From Source Requires [Bun](https://bun.sh). ```bash 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](/docs/session-matching/#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. ```sh # 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 1. Start your AI coding sessions in tmux panes as usual 2. Launch the picker: ```bash ccmux ``` 3. 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`): ```tmux # 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: ```tmux 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+. # Usage > Use the ccmux picker, preview panes, review diffs, enable notifications, and start agents. ## CLI Commands | Command | Description | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `ccmux` | Launch interactive TUI picker (default) | | `ccmux picker` | Launch TUI with options (`--preview`, `--icons