cmux

cmux

Controls the cmux macOS terminal app via its CLI socket API to orchestrate workspaces, panes, browser previews, sidebar status, and notifications.

Full CLI reference: references/api_reference.md

Quick Check

Always verify cmux is running before issuing commands:

cmux ping 2>/dev/null && echo "ok" || echo "cmux not available"

If unavailable, skip cmux enhancements silently — never block the main task.

Core Use Cases

1. Auto Preview Routing

When a dev server starts or an HTML file is created, open it in a right-side browser pane:

# Dev server detected (e.g. localhost:3000)
cmux new-pane --type browser --direction right --url http://localhost:3000

# HTML file created — serve it first, then preview
cd <project-dir> && python3 -m http.server 8080 &
cmux new-pane --type browser --direction right --url http://localhost:8080/<file>.html

When to trigger:

• Output contains localhost:PORT, 127.0.0.1:PORT, Server running, Listening on
• A .html file is written and the user would benefit from seeing it rendered
• superpowers or another skill opens a visual artifact

Direction heuristic: right for wide layouts, down for narrow/tall terminals.

---

2. Subagent Workspaces

When dispatching parallel agents (via superpowers:dispatching-parallel-agents or similar), give each agent its own named cmux workspace so it's visible in the sidebar:

# Create a workspace per agent (new-workspace has no --cwd — cd inside --command)
cmux new-workspace --command "cd /path/to/project && claude --dangerously-skip-permissions"
cmux rename-workspace "agent: fix-auth"

# Set status so the sidebar shows what the agent is doing
cmux set-status task "fix-auth" --icon "⚡"
cmux set-status state "running" --color "#F59E0B"

When an agent completes:

cmux notify --title "Agent done" --subtitle "fix-auth" --body "Merged and cleaned up"
cmux set-status state "done" --color "#10B981"

Pattern: workspace 1 = orchestrator, workspaces 2–8 = subagents. Use cmux list-workspaces --json to track IDs.