cmux

name	cmux
description	Drive the cmux native macOS terminal app from CLI or socket — workspaces, panes, surfaces, browser automation, notifications, sidebar metadata, session restore. Use whenever the user mentions cmux, wants to control terminal layout from an agent, automate browser panels on macOS, send notifications/flashes to the sidebar, or integrate an AI agent with cmux hooks. macOS only (14.0+).

cmux Control

cmux is a native macOS terminal app for running multiple AI coding agents in parallel. It exposes a CLI (cmux) and a Unix-socket JSON-RPC API (/tmp/cmux.sock) for full topology and browser control.

Core Concepts

• Window — top-level macOS cmux window
• Workspace — sidebar tab within a window (one git branch / project context)
• Pane — split region inside a workspace
• Surface — tab inside a pane (terminal or browser)

Handles default to short refs (workspace:2, pane:1, surface:7); UUIDs accepted as input. Add --id-format uuids|both for full IDs in output.

Detect cmux in a Shell

[ -S "${CMUX_SOCKET_PATH:-/tmp/cmux.sock}" ] || exit 0   # bail if not in cmux
[ -n "${CMUX_WORKSPACE_ID:-}" ] && echo "inside cmux surface"

Injected env vars in every cmux-spawned terminal: CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, CMUX_SOCKET_PATH, CMUX_PORT. Always anchor automation to CMUX_WORKSPACE_ID — the visually focused workspace may not be the agent's caller workspace.

Fast Start — Topology

cmux identify --json                              # who am I (window/workspace/pane/surface)
cmux tree                                         # full hierarchy
cmux list-workspaces --json
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"
cmux list-surfaces --workspace "$CMUX_WORKSPACE_ID"

cmux new-workspace --name "feature-x" --cwd /path/to/repo
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type terminal --direction right --focus false
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type browser  --direction right --url http://localhost:3000
cmux move-surface --surface surface:7 --pane pane:2 --focus false
cmux split-off --surface surface:7 right
cmux reorder-surface --surface surface:7 --before surface:3
cmux close-surface --surface surface:7

Send Input

cmux send "echo hi\n"                                       # focused terminal
cmux send-key "ctrl+c"                                       # enter|tab|esc|backspace|arrows|ctrl+x|shift+tab
cmux send-surface --surface surface:7 "npm run build\n"      # specific surface
cmux send-key-surface --surface surface:7 enter

Notifications & Sidebar Metadata

cmux notify --title "Done" --body "tests passed"
cmux set-status build "compiling" --icon hammer --color "#ff9500"
cmux set-progress 0.5 --label "Building..."
cmux log --level success "All 42 tests passed"               # info|progress|success|warning|error
cmux trigger-flash --workspace "$CMUX_WORKSPACE_ID"          # blue-ring attention cue
cmux sidebar-state --json                                    # dump all sidebar metadata

Browser Automation (WKWebView)

Workflow: open → wait → snapshot → act → re-snapshot.

S=$(cmux --json browser open https://example.com | jq -r .result.surface_ref)
cmux browser "$S" wait --load-state complete --timeout-ms 15000
cmux browser "$S" snapshot --interactive                     # returns elements as e1, e2, ...
cmux browser "$S" fill e1 "[e-mail]"
cmux browser "$S" click e2 --snapshot-after

# Navigation / inspection
cmux browser "$S" goto URL | back | forward | reload
cmux browser "$S" get url | get title | get text body | get value "#email" | get count ".row"
cmux browser "$S" eval 'return document.title'

# Waits
cmux browser "$S" wait --selector "#ready" --timeout-ms 10000
cmux browser "$S" wait --url-contains "/dashboard" --timeout-ms 10000

# Session
cmux browser "$S" cookies get | cookies set --name foo --value bar
cmux browser "$S" state save /tmp/auth.json | state load /tmp/auth.json

# Diagnostics
cmux browser "$S" console list | errors list | screenshot

Not supported by WKWebView (return not_supported): viewport emulation, geolocation/offline emulation, trace recording, network route interception, raw input injection.

Markdown Viewer

cmux markdown open plan.md --direction right                 # live-watching renderer
cmux open file.pdf                                           # auto-routes to right viewer

Settings & Config

cmux docs settings        # prints paths, schema URL, reload cmd — read BEFORE editing
cmux settings path        # path to cmux.json
cmux settings cmux-json   # open in editor
cmux reload-config        # hot-reload cmux.json + ~/.config/ghostty/config (Cmd+Shift+,)

Locations:

• cmux settings: ~/.config/cmux/cmux.json (canonical). Project-local override: .cmux/cmux.json or ./cmux.json.
• Terminal rendering (font, cursor, theme, scrollback, opacity, blur): ~/.config/ghostty/config — NOT cmux.json.

Before editing cmux.json, copy it to a timestamped .bak next to it so the user can revert. Schema: https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json.

Agent Hooks & Install

brew tap manaflow-ai/cmux && brew install --cask cmux
sudo ln -sf /Applications/cmux.app/Contents/Resources/bin/cmux /usr/local/bin/cmux
cmux hooks setup                                             # all detected agents
cmux hooks setup codex|grok|antigravity|opencode             # specific agent
npx skills add manaflow-ai/cmux -g -y                        # install cmux skills for agents

Native session-resume supported for: Claude Code, Codex, Grok, OpenCode, Pi, Amp, Cursor CLI, Gemini, Antigravity, Rovo Dev, Hermes, Copilot, CodeBuddy, Factory, Qoder.

Socket API (advanced)

/tmp/cmux.sock — Unix socket, JSON-RPC v2. Use for tight loops where subprocess spawn cost matters; otherwise prefer the CLI.

echo '{"id":"1","method":"workspace.list","params":{}}' | nc -U /tmp/cmux.sock

Method prefixes: system.*, window.*, workspace.*, pane.*, surface.*, notification.*, browser.*. Full list and Python client example in references/socket-api.md.

Access modes: cmuxOnly (default — only cmux-spawned processes), automation (any local process), password, allowAll (unsafe). If you hit Failed to connect to socket, you're likely an external process under cmuxOnly — switch mode in Settings > Automation or run from inside a cmux terminal.

Critical Rules — Non-Disruptive Automation

These rules come from the cmux-workspace skill and prevent agents from yanking the user's focus:

1. Anchor to CMUX_WORKSPACE_ID. Never assume the visually focused workspace is the target.
2. Never call focus-changing verbs speculatively. select-workspace, focus-pane, focus-panel, focus-surface only on explicit user request. Pass --focus false whenever available.
3. Build layout additively in one call. cmux new-pane --type … --focus false beats create-then-move-then-focus chains.
4. Right-side helper pane pattern. Reuse an existing non-caller helper pane if present; otherwise create exactly one right-side pane.
5. Never send input to surfaces you don't own. Only target surfaces in the caller's workspace unless the user explicitly asks for cross-workspace routing.
6. Check surface health before routing input when UI state may be stale: cmux surface-health.

Common Pitfalls

• Pi/Pi-like socket connection failures from external processes → default cmuxOnly mode; either run inside a cmux terminal or change socket mode.
• macOS only. No Linux/Windows port.
• WKWebView ≠ CDP. Don't expect Playwright-equivalent network mocking or viewport emulation.
• Resume strips sensitive env vars. Re-inject tokens at resume time if the agent needs them.
• Skills snapshot at app start. Edits to skill files require a restart of the consuming agent.
• Legacy v1 socket payloads ({"command":...}) rejected. Use v2 JSON-RPC only.
• Don't cat ~/.cmuxterm/*-hook-sessions.json expecting secrets — they're scrubbed. Look there for session/surface mappings only.

Reference: Full CLI Help

For any command, cmux <cmd> --help is authoritative. Use cmux capabilities --json to enumerate available socket methods in the current build.

Keyboard Shortcuts (most-used)

Workspaces: ⌘N new, ⌘1–8 jump, ⌃⌘[ / ⌃⌘] prev/next, ⌘⇧W close, ⌘B sidebar. Surfaces: ⌘T new, ⌘⇧[ / ⌘⇧] prev/next, ⌘W close, ⌃1–8 jump. Splits: ⌘D right, ⌘⇧D down, ⌥⌘D browser right, ⌥⌘←→↑↓ focus directional, ⌘⇧↵ zoom. Browser: ⌘⇧L open, ⌘L address bar, ⌘[/⌘] back/forward, ⌥⌘I devtools. App: ⌘, settings, ⌘⇧, reload-config, ⌘⇧P palette, ⌘⇧O restore session, ⌃⌥⌘. system-wide show/hide.