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
## โ Why?
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](#-custom-agents) 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](https://github.com/modem-dev/hunk), right in the pane
- ๐ค **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](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](#-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.
## ๐ 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"
> ```
>
> The picker exits after you select a session, so the popup closes itself and drops you straight into that pane. (`display-popup` requires tmux 3.2+.)
## ๐ฎ Usage
### CLI Commands
| Command | Description |
| :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------- |
| `ccmux` | Launch interactive TUI picker (default) |
| `ccmux picker` | Launch TUI with options (`--preview`, `--icons
