cmux-workspace

Source excerpt starting at line 1.

1---2name: cmux-workspace3description: "Work inside the current cmux workspace and terminal. Use for cmux workspace, current workspace, caller surface, panes, surfaces, socket targeting, and non-interfering cmux automation."4---5 6# cmux Workspace7 8Scope work to the cmux workspace that invoked the agent.9 10- **Window**: a macOS cmux window.11- **Workspace**: a sidebar entry. The UI calls it a tab; CLI/socket APIs call it a workspace.12- **Pane**: a split region inside a workspace.13- **Surface**: a tab inside a pane, terminal or browser.14- **Panel**: internal content type inside a surface. Prefer CLI surface commands over panel internals.15 16## Default rule17 18Scope actions to the current caller workspace unless the user explicitly asks for another workspace, another window, or global state. Do not assume the visually focused workspace is the right target: an agent can run in one workspace while the user looks at another.19 20```bash21printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \22  "${CMUX_WORKSPACE_ID:-}" "${CMUX_SURFACE_ID:-}" "${CMUX_SOCKET_PATH:-}"23cmux identify --json24```25 26`CMUX_WORKSPACE_ID` is the default workspace anchor and `CMUX_SURFACE_ID` the default caller terminal anchor. If they are missing, fall back to `cmux identify --json` and say explicitly that you are using the currently focused context.27 28## Non-disruptive automation29 30Treat layout and focus as separate concerns. `select-workspace`, `focus-pane`, `focus-panel`, and focus-changing `tab-action` verbs are user-affecting actions, like clicks. Never call them speculatively, even inside the caller's own workspace, since the user may be looking elsewhere.31 32Build layout additively in one shot, using commands that create a pane already populated with the right surface:33 34```bash35cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type browser --direction right --url "http://127.0.0.1:8765"36cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type terminal --direction down37cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type terminal --direction down --command "npm run dev"38```39 40When the first command for a new terminal is known, pass `--command <text>` so it starts at spawn instead of a later `send`. Avoid create-then-move-then-focus chains. Pass `--focus false` wherever the verb supports it (`move-surface --focus false` preserves the user's attention; more commands may grow the flag, see https://github.com/manaflow-ai/cmux/issues/1418 and https://github.com/manaflow-ai/cmux/issues/2820). If a layout command rejects a valid `surface:` or `pane:` ref, report the bug and stop rather than working around it by focusing.41 42## Right-side helper pane43 44For auxiliary output (preview apps, TUIs, logs, one-off shells, browser checks), reuse one helper pane to the right of the caller terminal. Inspect first with `cmux identify --json`, `cmux list-panes`, and `cmux list-pane-surfaces`, then:45 46- Helper pane exists: add a surface to it.47  ```bash48  cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:<helper> --type terminal --focus false49  ```50- No helper pane: create exactly one.51  ```bash52  cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false53  ```54- Multiple obvious stale helper panes from this same automation, and the user asked to tidy: keep one and clean up duplicates. Never close a pane you cannot confidently identify as stale helper output.55 56Send commands to the new or reused surface by explicit surface ref, or pass `--command <text>` at creation when the first command is already known. Repeated "open it" requests create tabs inside the existing right helper pane, not more splits.57 58## Caller terminal59 60The surface that invoked the agent is the safest anchor for relative operations.61 62```bash63cmux send "npm test\n"                                    # focused terminal in caller workspace64cmux send --surface "${CMUX_SURFACE_ID:-}" "git status\n"  # exact caller surface65cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter66```67 68Do not send keystrokes, close surfaces, or change focus in another workspace unless the user named that target.69 70## Moving surfaces71 72```bash73cmux move-surface --surface "${CMUX_SURFACE_ID}" --before surface:3   # also --after, --index74cmux move-surface --surface surface:240 --pane pane:172 --focus false75cmux drag-surface-to-split --surface surface:240 down76```77 78Known papercut: `drag-surface-to-split` routes through V1 and resolves the workspace via UI focus, so it fails with `ERROR: Surface not found` when the caller's workspace is not the visually focused one (https://github.com/manaflow-ai/cmux/issues/1901, related https://github.com/manaflow-ai/cmux/issues/3189). Until that lands, build layout additively. Never call `focus-pane` or `focus-panel` to recover from a failed move; report the failure and stop.79 80## Sidebar state81 82Attach status, progress, and logs to the current workspace so the sidebar reflects this task.83 84```bash85cmux set-status build "running" --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"86cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"87cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- "Started build"88cmux sidebar-state --workspace "${CMUX_WORKSPACE_ID:-}" --json89```90 91## Contributor reloads92 93For cmux app/runtime changes in a cmux source checkout, use a tagged reload from the active worktree. It creates an isolated app name, bundle ID, debug socket, and DerivedData path. Never build or launch untagged `cmux DEV`.94 95```bash96./scripts/reload.sh --tag <short-tag>97CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux identify --json98```99 100## Socket access101 102Use the socket path cmux provided before any default: `SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"`. Socket access can be off, restricted to cmux-spawned processes, or open to all local processes. If a command cannot connect, inspect `cmux capabilities --json` and `cmux ping` before changing settings.103 104## Rules105 106- Work in the caller workspace by default; prefer explicit `--workspace` and `--surface` flags for mutating actions even when env vars are set, so automation is auditable.107- Never call `focus-pane`, `focus-panel`, `select-workspace`, or focus-changing `tab-action` verbs unless the user explicitly asked.108- Pass `--focus false` on `move-surface` and any creation verb that supports it.109- Build layout additively with `new-pane --type ... --url ...` or `--command ...`, not create-then-move-then-focus.110- If a CLI command rejects a valid surface or pane ref, report it. Do not work around by focusing.111- Do not close, focus, move, or send input to another workspace unless the user names that target.112- Use short refs in chat and examples; UUIDs only for logs, persistence, or debugging.113 114## References115 116- [references/commands.md](references/commands.md): full workspace, pane, surface, notification, and utility command list.117- [../cmux-browser/SKILL.md](../cmux-browser/SKILL.md): browser surfaces under the same current-workspace rule.118