cmux

cmux

Use this skill when the current terminal is managed by cmux, or when the task needs cmux browser surfaces, workspace layout, markdown viewing, or cmux-specific agent launchers.

Detection

env | grep '^CMUX_'
cmux current-workspace
cmux sidebar-state

If CMUX_WORKSPACE_ID and CMUX_SURFACE_ID are present, route pane and browser operations through cmux.

Inspect Layout

cmux current-workspace
cmux tree --workspace workspace:N
cmux tree --all
cmux list-panes --workspace workspace:N
cmux list-pane-surfaces --workspace workspace:N --pane pane:N
cmux sidebar-state --workspace workspace:N

Always inspect layout first, then use explicit workspace:N, pane:N, and surface:N targets.

Read Screen

cmux read-screen --workspace workspace:N --surface surface:N --lines 80
cmux read-screen --workspace workspace:N --surface surface:N --scrollback --lines 200

Send Input

cmux send --workspace workspace:N --surface surface:N "command here"
cmux send-key --workspace workspace:N --surface surface:N "Enter"
cmux send-key --workspace workspace:N --surface surface:N "C-c"

Prefer sending full commands plus Enter; use keys for control sequences.

Workspaces, Panes, and Surfaces

cmux new-workspace --name "title" --cwd /path
cmux select-workspace --workspace workspace:N
cmux rename-workspace --workspace workspace:N "title"
cmux new-pane --type terminal --direction right --workspace workspace:N
cmux new-pane --type browser --direction right --workspace workspace:N --url https://example.com
cmux new-split right --workspace workspace:N --surface surface:N
cmux new-surface --type terminal --pane pane:N --workspace workspace:N
cmux new-surface --type browser --pane pane:N --workspace workspace:N --url https://example.com

In cmux, panes hold surfaces. A pane can contain terminal and browser surfaces as tabs.

Focus, Move, and Close

cmux focus-pane --pane pane:N --workspace workspace:N
cmux move-surface --surface surface:N --pane pane:N --workspace workspace:N
cmux move-tab-to-new-workspace --surface surface:N --workspace workspace:N --title "title" --focus false
cmux split-off --surface surface:N right --workspace workspace:N --focus false
cmux close-surface --surface surface:N --workspace workspace:N
cmux close-workspace --workspace workspace:N

To avoid recursive screen sharing during a video call, move the meeting browser surface into its own workspace instead of closing it:

cmux tree --workspace workspace:N
cmux move-tab-to-new-workspace --surface surface:N --workspace workspace:N --title meeting --focus false

Browser Surfaces

cmux browser --surface surface:N url
cmux browser --surface surface:N snapshot --compact
cmux browser --surface surface:N navigate https://example.com --snapshot-after
cmux browser --surface surface:N click "button"
cmux browser --surface surface:N type "input[name=q]" "text"
cmux browser --surface surface:N screenshot --out /tmp/cmux-browser.png

Prefer browser subcommands for cmux browser surfaces. Do not use them to click call controls, close tabs, or submit forms unless the user has asked for that specific action.

Markdown and Notifications

cmux markdown open /path/to/report.md --focus false
cmux notify --title "Done" --body "Details" --workspace workspace:N
cmux list-notifications

Browse Project Files

Use peek to browse the current cmux workspace in the cmux browser via a local code-server instance:

peek
peek ~/some-project

peek is a local machine setup, not a portable cmux command. It must only use a loopback code-server URL when authentication is disabled. If it opens the wrong folder, verify cmux sidebar-state reports the expected cwd; if incorrect, recreate the workspace with the right --cwd.

Agent Workflow

cmux new-workspace --name "agent task" --cwd /repo
cmux send --workspace workspace:N --surface surface:N "droid"
cmux send-key --workspace workspace:N --surface surface:N "Enter"

cmux-specific launchers include cmux codex-teams, cmux claude-teams, and cmux hermes. Use the normal agent CLI directly when you need exact command control.

Hooks

When the user asks for /cmux hooks, use the dotagents layer rather than cmux hooks setup. Cmux hook entrypoints are repo-owned under ~/.agents/hooks/cmux/, declared in ~/.agents/dotagents.yaml, and distributed with:

dotagents sync --agents=codex,droid,hermes

Do not let cmux hooks setup patch agent configs directly unless the user explicitly asks to bypass dotagents.

Safety Rules

• Inspect layout before reading, sending input, moving surfaces, or closing anything.
• Use explicit targets (workspace:N, pane:N, surface:N).
• Move browser/video surfaces to a separate workspace instead of closing them to avoid terminating active sessions.
• Do not click browser controls, close surfaces, or send destructive commands unless you have verified the target and the user asked for that action.
• Prefer a dedicated workspace for long-running delegated agents.