cmux-ctl 0.1.0

TUI dashboard for orchestrating cmux workspaces and Claude Code agents

cmux-ctl

A terminal dashboard for orchestrating cmux workspaces and Claude Code agents.

Built with Textual.

Features

• Real-time dashboard — grid of workspace cards, auto-refreshing every 3 seconds
• Agent state tracking — running, waiting for input, idle, with color-coded borders
• Live terminal preview — last 15 lines of each workspace's terminal output
• Launch agents — start Claude Code in new or existing workspaces from the dashboard
• Send input / stop agents — interact with agents without switching windows
• Notification badges — unread alerts surfaced per workspace
• Stale detection — agents whose output hasn't changed in 30s are flagged
• Keyboard-first — full grid navigation, no mouse required

Prerequisites

• macOS with cmux installed and running
• Python 3.10+

Installation

pipx (recommended)

pipx install cmux-ctl

pip

pip install cmux-ctl

From source

git clone https://github.com/alaasdk/cmux-ctl.git
cd cmux-ctl
pip install -e .

Usage

cmux-ctl

That's it. The dashboard connects to cmux automatically and displays all active workspaces.

Keybindings

Key	Action
q	Quit
r	Refresh
l	Launch agent
s	Stop agent (sends Ctrl+C)
i	Send input to agent
Enter	Switch to workspace in cmux
Tab / Shift+Tab	Next / previous card
Arrow keys	Grid navigation

Configuration

Environment Variable	Description	Default
CMUX_BIN	Path to the cmux binary	/Applications/cmux.app/Contents/Resources/bin/cmux

How it works

cmux-ctl communicates with cmux entirely through its CLI:

1. cmux tree --all --json — discovers all workspaces, panes, and surfaces
2. cmux sidebar-state — reads workspace metadata (cwd, git branch, PR links, agent state)
3. cmux read-screen — captures terminal output for live preview
4. Session map (/tmp/cmux-session-map.json) — detects active Claude Code sessions

The dashboard polls every 3 seconds for workspace state and every 2 seconds for terminal content. Agent state is determined from sidebar metadata, screen content heuristics (e.g., detecting Claude Code's UI patterns), and the session map.

Development

git clone https://github.com/alaasdk/cmux-ctl.git
cd cmux-ctl
pip install -e .

# Run with Textual dev mode (live CSS reload, console)
make dev

License

MIT