ccmux CLI
ccmux tracks every coding agent in tmux: who is working, who waits for you, worktree spawning and answer hand-off.
- 239 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- `ccmux setup` writes hooks into agent configuration
- Approve and Deny buttons in notifications authorise agent actions, and replies are typed into another pane
- `ccmux invoke` runs Copilot with the `--allow-all-tools` flag
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/ccmuxDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- `ccmux setup` writes hooks into agent configuration
- Approve and Deny buttons in notifications authorise agent actions, and replies are typed into another pane
- `ccmux invoke` runs Copilot with the `--allow-all-tools` flag
This is third-party code. Review the repository files before installing.
What it does
ccmux is a background daemon and TUI for coding-agent sessions in tmux. It finds Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity, Copilot and Gemini CLI in panes, shows each one's state (idle, working, waiting for permission, a plan or an answer) and jumps to the right pane on Enter. Agents are launched as usual; no reconfiguration is needed. From the panel you spawn and fork sessions into fresh git worktrees, review diffs through hunk and move uncommitted changes out. `ccmux invoke` runs a single agent turn for scripts and `ccmux handoff` passes the last answer to another agent. The repository ships two skills: `dispatch` and `relay`.
Who it is for. Developers who keep several agents in tmux panes and lose track of which one is waiting for permission.
Good fit when
- Five agents work in different panes and you need to find the one waiting for approval.
- One task is tried on several branches, each session in its own git worktree.
- Codex's answer is handed to Claude Code with a note using `ccmux handoff codex claude`.
- An orchestrator agent starts workers through `ccmux invoke` and reads their results.
- A permission request is approved or denied straight from a desktop notification.
Not a fit when
- Agents run outside tmux.
- Agent configuration hooks must not be changed, and `ccmux setup` writes them.
- You want a graphical session manager without a terminal.
Example request
Show which of my tmux agents are waiting for permission and hand Codex's last answer to the Claude Code session with a note.Limitations
Works only with agents inside tmux; git 2.31 or newer is needed for branch and worktree details. `ccmux setup` installs hooks into the configuration of detected agents for accurate session matching. Without hooks ccmux still works, with less precision. Notifications with Approve and Deny buttons are off by default and decide for an agent without opening its pane. Replying to a permission request from a notification is supported only for Claude Code. A sandbox without write access to `~/.config/ccmux` strips the hooks' markers. Building from source needs Bun 1.3.14 or newer.
How to disable. Run `brew uninstall ccmux` and stop the background daemon. Remove the hooks created by `ccmux setup` from the agents' configuration by hand and uninstall the plugin through `/plugin`.
FAQ
Do agents need a special launch?
No. ccmux finds them in tmux panes and picks up processes already running.
What does `ccmux setup` install?
Agent hooks for exact matching of sessions to panes. Without them the daemon relies on processes and logs.
How do I hand work to another agent?
With `ccmux handoff codex claude --note "..."`. The answer arrives with a provenance header and is typed only into an idle composer.
Which agents are supported?
Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity, Copilot, Gemini CLI and custom definitions through config.
How do I enable notifications?
With `ccmux config set notifications.enabled true`; `ccmux notify` sends a test notification and prints diagnostics. Approve and Deny buttons work on macOS and Linux.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI and terminal app that show which coding agents in your tmux sessions are working, waiting on you or done
A tmux-based TUI that runs Claude Code, Codex and other agents in one list: status, quick prompts, worktrees and diff review
A tuned tmux setup and the tmux-bridge CLI that lets agents read neighbouring panes, type into them and hand each other tasks.
A Go terminal multiplexer with tiled panes that shows the state of Claude Code, Codex and other agents and gathers their requests in one list
A terminal workspace where several CLI agents like Codex, Claude and Gemini exchange messages and work on one task under human oversight
A control plane that runs Claude Code, Codex and Gemini CLI agents in parallel with a shared task board and schedules
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| ccmux (this card) | no | 239 | |
| tmux-ide | yes | 563 | shows which agents in tmux sessions are working, waiting or done; ccmux adds worktrees, answer hand-off and `invoke` |
| CLI Agent Orchestrator | no | 1,515 | coordinates agents through a supervisor in tmux sessions; ccmux watches sessions already running and hands work between them |
README in short
Install through Homebrew or from source, a quick start with `ccmux`, panels, a sidebar and notifications. Worktrees, session forking, `invoke`, `handoff`, matching hooks and skills are covered in detail.