Cmux Workspace

This skill teaches Claude to work inside the cmux workspace that called it, without hijacking your focus or spawning surprise splits in the wrong window. It enforces a "caller context first" rule using `CMUX_WORKSPACE_ID` and `CMUX_SURFACE_ID`, so automation stays scoped even when you're looking at a different tab. The big win is the non-disruptive policy: no speculative `select-workspace` or `focus-pane` calls, additive layout commands that create panes with content in one shot, and a right-side helper pane pattern that reuses space instead of cluttering your workspace. If you run agents in the background or multi-task across cmux workspaces, this keeps the automation polite and the layout predictable.

skills.sh installs: 7.2K
GitHub stars: 28.7K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add manaflow-ai/cmux --skill cmux-workspace --agent claude-code

Installs into .claude/skills of the current project.

Files

cmux Workspace

Scope work to the cmux workspace that invoked the agent.

Window: a macOS cmux window.
Workspace: a sidebar entry. The UI calls it a tab; CLI/socket APIs call it a workspace.
Pane: a split region inside a workspace.
Surface: a tab inside a pane, terminal or browser.
Panel: internal content type inside a surface. Prefer CLI surface commands over panel internals.

Default rule

Scope 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.

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

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.