cmux-workspace

cmux Workspace scopes an agent's actions to the cmux workspace that invoked it and to the caller terminal within that workspace. In cmux, a workspace is a sidebar tab-like unit containing split panes, each pane contains one or more surfaces, and a surface is the terminal or browser session the user interacts with. The default rule is to scope actions to the current caller workspace unless the user explicitly asks for another workspace, window, or global state -- and crucially, not to assume the visually focused workspace is the right target, since an agent may run in one workspace while the user looks at another. The caller environment is read from CMUX_WORKSPACE_ID and CMUX_SURFACE_ID, falling back to `cmux identify --json` when those are missing.

A central theme is non-disruptive automation: layout and focus are separate concerns, and focus-changing verbs must never be called speculatively. Commands like select-workspace, focus-pane, focus-panel, and focus-changing tab-action variants are treated as user-affecting actions (like clicks) and are only used on an explicit request, even within the caller's own workspace. The preferred approach is to build layout additively in one shot -- for example `cmux new-pane` that creates a pane already populated with the right surface -- and to pass `--focus false` wherever a verb supports it (such as move-surface) to preserve the user's attention. Auxiliary output for a task (preview apps, TUIs, logs, one-off shells, browser checks) is kept tidy by reusing a single right-side helper pane: inspect existing panes, add a new surface to an existing helper pane when one exists, or create exactly one right-side pane otherwise.

The skill documents the cmux hierarchy (window, workspace, pane, surface, panel) and provides inspection commands such as `cmux identify`, `cmux current-workspace`, `cmux list-workspaces`, `cmux list-panes`, and `cmux list-pane-surfaces`, with `--json` and `--id-format both` for stable UUIDs plus human refs. Workspace-scoped actions prefer explicit workspace flags for auditability and include creating, renaming, and closing workspaces and surfaces, sending input to the caller terminal with `cmux send`, moving and splitting surfaces, and attaching status, progress, and log state to the sidebar. It also notes known papercuts (for example drag-surface-to-split resolving via UI focus) and advises reporting layout-command failures and stopping rather than recovering by forcing focus.