cmux

Use this skill for the manaflow-ai/cmux terminal multiplexer app: topology control, current-workspace automation, embedded browser surfaces, settings, shortcuts, and socket-safe operations. Do not use it for the unrelated craigsc/cmux Bash worktree helper.

Core Philosophy

1. Caller context beats visual focus. Agents may run in one cmux workspace while the user looks elsewhere. Anchor automation on CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, and CMUX_SOCKET_PATH first.
2. Build additively. Prefer new-pane / new-surface with explicit targets over create-move-focus chains that can steal attention.
3. Focus is user-visible. Treat select-workspace, focus-pane, focus-panel, and focus-changing tab actions like clicks: run only when the user asked for a visible focus change.
4. Snapshot before browser actions. Browser element refs go stale after DOM or navigation changes. Snapshot, act, wait, then snapshot again.
5. Edit settings surgically. Change only supported cmux.json paths, validate, and rely on live reload instead of telling the user to restart.

Fast Start

# inspect caller context
printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" "${CMUX_SURFACE_ID:-}" "${CMUX_SOCKET_PATH:-}"
cmux identify --json

# list topology
cmux list-windows --json
cmux list-workspaces --json
cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json

# non-disruptive helper pane in the caller workspace
cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false

# embedded browser surface workflow
cmux --json browser open http://127.0.0.1:3000 --workspace "${CMUX_WORKSPACE_ID:-}"
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive

# settings and reload
cmux docs settings
cmux settings path
cmux reload-config

Quick-Start: Common Problems

"Open a pane/browser/logs without disrupting me"

1. Run cmux identify --json and use the caller workspace.
2. Reuse an existing helper pane when obvious; otherwise create one right-side helper pane with --focus false.
3. Send commands by explicit --surface instead of focusing the pane.

See references/topology-and-workspace.md.

"Automate a web page inside cmux"

1. Open or target one browser surface.
2. get url, wait for state, take snapshot --interactive.
3. Use returned refs (e1, e2, ...) for click, fill, press, select.
4. Re-snapshot after every navigation or DOM-changing action.

See references/browser-automation.md.

"Change a cmux setting or shortcut"

1. Prefer the cmux settings helper if available; otherwise edit ~/.config/cmux/cmux.json carefully.
2. Change only the named setting path, not whole top-level sections.
3. Validate and reload with cmux reload-config.

See references/settings-and-shortcuts.md.

"A cmux command cannot connect"

1. Use CMUX_SOCKET_PATH before falling back to /tmp/cmux.sock.
2. Run cmux ping and cmux capabilities --json.
3. Inspect automation socket policy before changing access settings.

See references/socket-diagnostics-and-safety.md.

Decision Trees

Which surface command?

Need	Command family	Safety note
Inspect where the agent is	identify, current-workspace	Safe default first step
Add task output	new-pane, new-surface	Pass caller workspace and --focus false
Move/reorder tabs	move-surface, reorder-surface	Preserve focus unless asked
User explicitly wants visible focus	select-workspace, focus-pane, focus-panel	User-visible action
Show attention cue	trigger-flash	Safer than stealing focus
Close something	close-surface, close-workspace	Confirm target from refs first

Browser automation loop

Step	Command	Why
Open/target	cmux browser open <url>	Returns a surface ref
Verify	get url	Avoid waiting on about:blank
Wait	wait --selector/text/url-contains/load-state	Deterministic readiness
Inspect	snapshot --interactive	Fresh element refs
Act	click, fill, press, select	Use refs from latest snapshot
Recover	get text body, get html body	Fallback when rich snapshot JS fails

Settings vs Ghostty config

Desired change	File/tool
App behavior, sidebar, notifications, browser, automation, cmux shortcuts	~/.config/cmux/cmux.json
Font, cursor, terminal theme, scrollback, opacity, blur	~/.config/ghostty/config
Apply cmux-owned settings	Save file or run cmux reload-config
Inspect docs/schema	cmux docs settings

Reference Index

File	Contents
references/topology-and-workspace.md	Windows, workspaces, panes, surfaces, handles, caller-scoped automation, helper panes
references/browser-automation.md	Embedded browser surfaces, wait/snapshot/action loop, stale refs, auth/session patterns, WKWebView limits
references/settings-and-shortcuts.md	cmux.json, settings helper workflow, live reload, shortcut binding templates and cautions
references/socket-diagnostics-and-safety.md	Socket access, focus policy, diagnostics, health checks, contributor-only boundaries