| name | cmux |
|---|---|
| description | End-user control of cmux topology and routing (windows, workspaces, panes/surfaces, focus, moves, reorder, identify, trigger flash). Use when automation needs deterministic placement and navigation in a multi-pane cmux layout. |
Use this skill to control non-browser cmux topology and routing.
- Window: top-level macOS cmux window.
- Workspace: tab-like group within a window.
- Pane: split container in a workspace.
- Surface: a tab within a pane (terminal or browser panel).
# identify current caller context
cmux identify --json
# list topology
cmux list-windows
cmux list-workspaces
cmux list-panes
cmux list-pane-surfaces --pane pane:1
# create/focus/move
cmux new-workspace
cmux new-split right --panel pane:1
cmux move-surface --surface surface:7 --pane pane:2 --focus true
cmux split-off --surface surface:7 right
cmux reorder-surface --surface surface:7 --before surface:3
# attention cue
cmux trigger-flash --surface surface:7Use cmux docs settings before changing cmux-owned settings. It prints the docs URL, schema URL, raw GitHub resources, cmux.json paths, and reload command.
cmux docs settings
cmux settings pathcmux-owned settings live in ~/.config/cmux/cmux.json. Legacy ~/.config/cmux/settings.json and ~/Library/Application Support/com.cmuxterm.app/settings.json files are read only as fallback for missing keys. Before editing, copy any existing cmux.json file to a timestamped .bak next to it so the user can revert. Edit the user file, then reload:
cmux reload-configcmux reload-config reloads BOTH cmux.json and Ghostty config (~/.config/ghostty/config) and refreshes terminals in place. No app restart needed.
Use cmux settings for app behavior, sidebar, notifications, browser behavior, automation, workspace colors, and cmux-owned shortcuts. Terminal rendering settings such as font, cursor style, theme, scrollback, background transparency (background-opacity), and blur (background-blur) belong in Ghostty config at ~/.config/ghostty/config.
Open the UI when useful:
cmux settings
cmux settings cmux-json
cmux settings shortcuts- Default output uses short refs:
window:N,workspace:N,pane:N,surface:N. - UUIDs are still accepted as inputs.
- Request UUID output only when needed:
--id-format uuids|both.
| Reference | When to Use |
|---|---|
| references/handles-and-identify.md | Handle syntax, self-identify, caller targeting |
| references/windows-workspaces.md | Window/workspace lifecycle and reorder/move |
| references/panes-surfaces.md | Splits, surfaces, move/reorder, focus routing |
| references/trigger-flash-and-health.md | Flash cue and surface health checks |
| ../cmux-browser/SKILL.md | Browser automation on surface-backed webviews |
| ../cmux-markdown/SKILL.md | Markdown viewer panel with live file watching |
cmux - control cmux via Unix socket
Usage:
cmux <path> Open a directory in a new workspace (launches cmux if needed)
cmux [global-options] <command> [options]
Handle Inputs:
Use UUIDs, short refs (window:1/workspace:2/pane:3/surface:4), or indexes where commands accept window, workspace, pane, or surface inputs.
`tab-action` also accepts `tab:<n>` in addition to `surface:<n>`.
Output defaults to refs; pass --id-format uuids or --id-format both to include UUIDs.
Socket Auth:
--password takes precedence, then CMUX_SOCKET_PASSWORD env var, then password saved in Settings.
Agent Help:
To change cmux settings, run `cmux docs settings` and `cmux settings path`; to add Dock controls, run `cmux docs dock`.
Back up any existing cmux.json file to a timestamped .bak copy before editing.
Use printed curl commands to fetch the latest docs/schema, and prefer Ghostty config for terminal behavior Ghostty already supports.
Commands:
welcome
docs [settings|shortcuts|api|browser|agents|dock]
settings [open [target]|path|docs|<target>]
config <doctor|check|validate|path|paths|docs|documentation|reload>
shortcuts
disable-browser | enable-browser | browser-status
restore-session
feedback [--email <email> --body <text> [--image <path> ...]]
feed tui|clear
themes [list|set|clear]
claude-teams [claude-args...]
omo [opencode-args...]
omx [omx-args...]
omc [omc-args...]
hooks setup|uninstall [--agent <name>]
hooks <agent> <install|uninstall|event> [options; opencode supports --project]
hooks feed --source <agent> [--event <event>]
ping
version
capabilities
events [--after <seq>] [--cursor-file <path>] [--name <event>] [--category <category>] [--reconnect] [--limit <n>] [--no-ack] [--no-heartbeat]
auth <status|login|logout>
login | logout (aliases for auth login/logout)
vm <new|ls|rm|exec|shell|ssh> [args...] (alias: cloud)
rpc <method> [json-params]
identify [--workspace <id|ref|index>] [--surface <id|ref|index>] [--no-caller]
list-windows
current-window
new-window
focus-window --window <id>
close-window --window <id>
move-workspace-to-window --workspace <id|ref> --window <id|ref>
reorder-workspace --workspace <id|ref|index> (--index <n> | --before <id|ref|index> | --after <id|ref|index>) [--window <id|ref|index>]
workspace-action --action <name> [--workspace <id|ref|index>] [--title <text>] [--color <name|#hex>] [--description <text>]
move-tab-to-new-workspace [--tab <id|ref|index>] [--surface <id|ref|index>] [--workspace <id|ref|index>] [--title <text>] [--focus <true|false>]
list-workspaces
new-workspace [--name <title>] [--description <text>] [--cwd <path>] [--command <text>] [--layout <json>] [--focus <true|false>]
ssh <destination> [--name <title>] [--port <n>] [--identity <path>] [--ssh-option <opt>] [--no-focus] [-- <remote-command-args>]
remote-daemon-status [--os <darwin|linux>] [--arch <arm64|amd64>]
new-split <left|right|up|down> [--workspace <id|ref>] [--surface <id|ref>] [--panel <id|ref>] [--focus <true|false>]
list-panes [--workspace <id|ref>]
list-pane-surfaces [--workspace <id|ref>] [--pane <id|ref>]
tree [--all] [--workspace <id|ref|index>]
top [--all] [--workspace <id|ref|index>] [--processes]
focus-pane --pane <id|ref> [--workspace <id|ref>]
new-pane [--type <terminal|browser>] [--direction <left|right|up|down>] [--workspace <id|ref>] [--url <url>] [--focus <true|false>]
new-surface [--type <terminal|browser>] [--pane <id|ref>] [--workspace <id|ref>] [--url <url>] [--focus <true|false>]
close-surface [--surface <id|ref>] [--workspace <id|ref>]
move-surface --surface <id|ref|index> [--pane <id|ref|index>] [--workspace <id|ref|index>] [--window <id|ref|index>] [--before <id|ref|index>] [--after <id|ref|index>] [--index <n>] [--focus <true|false>]
split-off --surface <id|ref|index> <left|right|up|down> [--workspace <id|ref|index>] [--focus <true|false>]
reorder-surface --surface <id|ref|index> (--index <n> | --before <id|ref|index> | --after <id|ref|index>) [--focus <true|false>]
tab-action --action <name> [--tab <id|ref|index>] [--surface <id|ref|index>] [--workspace <id|ref|index>] [--title <text>] [--url <url>] [--focus <true|false>]
rename-tab [--workspace <id|ref>] [--tab <id|ref>] [--surface <id|ref>] <title>
drag-surface-to-split --surface <id|ref|index> <left|right|up|down> [--workspace <id|ref|index>] [--focus <true|false>]
refresh-surfaces
reload-config
surface-health [--workspace <id|ref>]
debug-terminals
trigger-flash [--workspace <id|ref>] [--surface <id|ref>]
list-panels [--workspace <id|ref>]
focus-panel --panel <id|ref> [--workspace <id|ref>]
close-workspace --workspace <id|ref>
select-workspace --workspace <id|ref>
rename-workspace [--workspace <id|ref>] <title>
rename-window [--workspace <id|ref>] <title>
current-workspace
read-screen [--workspace <id|ref>] [--surface <id|ref>] [--scrollback] [--lines <n>]
send [--workspace <id|ref>] [--surface <id|ref>] <text>
send-key [--workspace <id|ref>] [--surface <id|ref>] <key>
send-panel --panel <id|ref> [--workspace <id|ref>] <text>
send-key-panel --panel <id|ref> [--workspace <id|ref>] <key>
notify --title <text> [--subtitle <text>] [--body <text>] [--workspace <id|ref>] [--surface <id|ref>]
list-notifications
clear-notifications
set-status <key> <value> [--workspace <id|ref>] [--icon <name>] [--color <#hex>]
clear-status <key> [--workspace <id|ref>]
list-status [--workspace <id|ref>]
set-progress <0.0-1.0> [--label <text>] [--workspace <id|ref>]
clear-progress [--workspace <id|ref>]
log [--level <level>] [--source <name>] [--workspace <id|ref>] <message>
clear-log [--workspace <id|ref>]
list-log [--workspace <id|ref>] [--limit <n>]
sidebar-state [--workspace <id|ref>]
set-app-focus <active|inactive|clear>
simulate-app-active
# tmux compatibility commands
capture-pane [--workspace <id|ref>] [--surface <id|ref>] [--scrollback] [--lines <n>]
resize-pane --pane <id|ref> [--workspace <id|ref>] (-L|-R|-U|-D) [--amount <n>]
pipe-pane --command <shell-command> [--workspace <id|ref>] [--surface <id|ref>]
wait-for [-S|--signal] <name> [--timeout <seconds>]
swap-pane --pane <id|ref> --target-pane <id|ref> [--workspace <id|ref>] [--focus <true|false>]
break-pane [--workspace <id|ref>] [--pane <id|ref>] [--surface <id|ref>] [--focus <true|false>] [--no-focus]
join-pane --target-pane <id|ref> [--workspace <id|ref>] [--pane <id|ref>] [--surface <id|ref>] [--focus <true|false>] [--no-focus]
next-window | previous-window | last-window
last-pane [--workspace <id|ref>]
find-window [--content] [--select] <query>
clear-history [--workspace <id|ref>] [--surface <id|ref>]
set-hook [--list] [--unset <event>] | <event> <command>
popup
bind-key | unbind-key | copy-mode
set-buffer [--name <name>] <text>
list-buffers
paste-buffer [--name <name>] [--workspace <id|ref>] [--surface <id|ref>]
respawn-pane [--workspace <id|ref>] [--surface <id|ref>] [--command <cmd>]
display-message [-p|--print] <text>
markdown [open] <path> [--focus <true|false>] (open markdown file in formatted viewer panel with live reload)
browser [--surface <id|ref|index> | <surface>] <subcommand> ...
browser disable | enable | status
browser open [url] [--focus <true|false>] (create browser split in caller's workspace; if surface supplied, behaves like navigate)
browser open-split [url]
browser goto|navigate <url> [--snapshot-after]
browser back|forward|reload [--snapshot-after]
browser url|get-url
browser snapshot [--interactive|-i] [--cursor] [--compact] [--max-depth <n>] [--selector <css>]
browser eval <script>
browser wait [--selector <css>] [--text <text>] [--url-contains <text>] [--load-state <interactive|complete>] [--function <js>] [--timeout-ms <ms>]
browser click|dblclick|hover|focus|check|uncheck|scroll-into-view <selector> [--snapshot-after]
browser type <selector> <text> [--snapshot-after]
browser fill <selector> [text] [--snapshot-after] (empty text clears input)
browser press|keydown|keyup <key> [--snapshot-after]
browser select <selector> <value> [--snapshot-after]
browser scroll [--selector <css>] [--dx <n>] [--dy <n>] [--snapshot-after]
browser screenshot [--out <path>] [--json]
browser get <url|title|text|html|value|attr|count|box|styles> [...]
browser is <visible|enabled|checked> <selector>
browser find <role|text|label|placeholder|alt|title|testid|first|last|nth> ...
browser frame <selector|main>
browser dialog <accept|dismiss> [text]
browser download [wait] [--path <path>] [--timeout-ms <ms>]
browser profiles <list|add|rename|clear|delete> [...]
browser profiles clear <profile|--all> [--force]
browser import [...]
browser cookies <get|set|clear> [...]
browser storage <local|session> <get|set|clear> [...]
browser tab <new|list|switch|close|<index>> [...]
browser console <list|clear>
browser errors <list|clear>
browser highlight <selector>
browser state <save|load> <path>
browser addinitscript <script>
browser addscript <script>
browser addstyle <css>
browser identify [--surface <id|ref|index>]
help
Environment:
CMUX_WORKSPACE_ID Auto-set in cmux terminals. Used as default --workspace for
ALL commands (send, list-panels, new-split, notify, etc.).
CMUX_TAB_ID Optional alias used by `tab-action`/`rename-tab` as default --tab.
CMUX_SURFACE_ID Auto-set in cmux terminals. Used as default --surface.
CMUX_SOCKET_PATH Override the Unix socket path. Without this, the CLI defaults
to ~/Library/Application Support/cmux/cmux.sock and auto-discovers tagged/debug sockets.