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.

3. Sidebar Status & Progress

Show live feedback for long-running tasks without interrupting the main session:

# Task start
cmux set-progress 0 --label "Building..."
cmux set-status phase "build" --icon "🔨"

# Midpoint update
cmux set-progress 0.5 --label "Running tests..."
cmux set-status phase "test" --icon "🧪"

# Completion
cmux set-progress 1 --label "Done"
cmux notify --title "Task complete" --body "All tests passed"
cmux clear-progress

Use cmux log <message> --level info to append entries to the workspace log panel (visible via ⌘I).

When to use: any task taking >10 seconds — file processing, test runs, builds, research sweeps, code generation loops.

4. Utility Splits on Demand

Open any content in a split pane in the requested direction:

# Open a URL in a browser split
cmux new-pane --type browser --direction right --url <url>

# Open a terminal split running a command (e.g. log tail)
cmux new-pane --type terminal --direction down
cmux send "tail -f /path/to/server.log"
cmux send-key "Enter"

# Resize to make it a narrow utility strip
cmux resize-pane --pane <id> -D --amount 20   # shrink height by 20 rows

Direction mapping for natural language:

5. Workspace & Tab Actions

workspace-action and tab-action expose the right-click context-menu actions. Full table with flags in references/api_reference.md — the available action names are:

cmux workspace-action --action <name> (sidebar workspaces): pin · unpin · rename (needs --title) · clear-name · move-up · move-down · move-top · mark-read · mark-unread · close-others · close-above · close-below

cmux tab-action --action <name> (horizontal tabs): rename · clear-name · pin · unpin · reload · duplicate · new-terminal-right · new-browser-right · mark-read · mark-unread · close-left · close-right · close-others

⚠️ Destructive actions act on OTHER tabs, not the one you name. close-others / close-above / close-below (workspace) and close-left / close-right / close-others (tab) close everything except the target. close-others spares pinned workspaces only. Never run these to "test" — they will close the user's live tabs. Prefer close-workspace --workspace <id> to close one specific workspace.

Renaming / selecting (common gotchas):

• Rename the sidebar/switcher label → cmux workspace-action --action rename --title "<name>" (or cmux rename-workspace <name>). rename-tab only renames an inner tab and does not change the switcher label.
• Select/focus a workspace → cmux select-workspace --workspace <id>. There is no --action select (it errors "Unknown workspace action").

When unsure of a command's exact flags, run cmux <command> --help — every command embeds full usage.

Combining Use Cases

Full workflow example — superpowers runs a subagent that builds a UI:

# 1. Announce work in sidebar
cmux set-progress 0 --label "Scaffolding UI..."
cmux set-status agent "ui-builder" --icon "🎨"

# 2. Subagent does its work...

# 3. Server starts → auto-preview
cmux new-pane --type browser --direction right --url http://localhost:5173

# 4. Mark done
cmux set-progress 1 --label "Preview ready"
cmux notify --title "UI ready" --body "Preview open on the right"
cmux clear-progress

Demo Mode (/cmux demo)

When invoked as /cmux demo, run an interactive personalized walkthrough. Always verify cmux ping first — abort with a clear message if unavailable.

Screen 1 — Workflow

Ask with AskUserQuestion:

question: "What best describes how you work?"
header: "Workflow"
options:
  - label: "Coding agent manager"
    description: "Running multiple Claude sessions in parallel"
  - label: "Web dev"
    description: "Browser preview, dev servers, HTML artifacts"
  - label: "Research / long tasks"
    description: "Vault work, builds, sweeps that take minutes"
  - label: "Show me everything"
    description: "Run all demos back to back"

Screen 2 — Mode

question: "How do you want to explore?"
header: "Demo mode"
options:
  - label: "Walk me through it"
    description: "Step by step with explanations between each demo"
  - label: "Auto-run"
    description: "Run all relevant demos back to back, narrate as you go"
  - label: "Just the commands"
    description: "Show what you'd run, skip execution"

Screen 3 — tmux

question: "Do you use tmux?"
header: "tmux"
options:
  - label: "Yes, daily"
    description: "Show me the cmux + tmux combo"
  - label: "For SSH / remote only"
    description: "Show the remote persistence pattern"
  - label: "Not really"
    description: "Skip tmux, focus on cmux-native features"