/cmux

name: cmux
description: Controls the cmux macOS terminal app (Ghostty-based, AI-agent-aware) via its CLI socket API. Use this skill to: open browser preview panes when a dev server starts or an HTML file is created; spin up named workspaces for parallel subagents; show live sidebar progress/status during long tasks; open utility splits on demand (logs, URLs, terminals) in any direction. Also handles `/cmux demo` — an interactive walkthrough with 3 screens of options that runs personalized live demos. Trigger when: a server starts and needs previewing, an HTML/URL artifact is created, parallel subagents are dispatched, a long task needs visible progress, the user asks to open/show something in a split or tab, or the user invokes `/cmux demo`.

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:** | User says | Direction flag | |---|---| | "on the right" / "beside" | `--direction right` | | "on the left" | `--direction left` | | "below" / "at the bottom" | `--direction down` | | "above" / "at the top" | `--direction up` | | "in a new tab" / "new workspace" | `cmux new-workspace` |

---

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 fu