Track all your AI coding agents (Claude Code, Codex, Cursor, ...) in tmux and jump to the one that needs you

## ❓ 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 - 📝 **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, kill, and restart sessions from the TUI; `ccmux invoke` for scripted one-shot agent turns - ⌨️ **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 ### Homebrew brew install epilande/tap/ccmux ccmux setup ### From Source Requires [Bun](https://bun.sh). 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: ccmux 3. Navigate with j/k, press Enter to switch to a session ## 🎮 Usage ### CLI Commands | Command | Description | | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------ | | `ccmux` | Launch interactive TUI picker (default) | | `ccmux picker` | Launch TUI with options (`--preview`, `--icons