Back to Details

cmux-workspace

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cmux Workspace

cmux 工作区

Use this skill when a task should be scoped to the cmux workspace that invoked the agent. A workspace is the sidebar tab-like unit in cmux. It contains split panes, and each pane contains one or more surfaces. A surface is the terminal or browser session the user interacts with.
当任务需要限定在调用Agent的cmux工作区内执行时，使用此技能。工作区是cmux中类似侧边栏标签的单元，包含拆分的窗格，每个窗格又包含一个或多个界面（Surface）。界面指的是用户与之交互的终端或浏览器会话。

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 cmux workspace is the right target. An agent can be running in one workspace while the user is looking at another. Prefer the caller environment first:
bash
printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" \
  "${CMUX_SURFACE_ID:-}" \
  "${CMUX_SOCKET_PATH:-}"
cmux identify --json
Use 
CMUX_WORKSPACE_ID
as the default workspace anchor and 
CMUX_SURFACE_ID
as the default caller terminal/surface anchor. If those are missing, use 
cmux identify --json
and be explicit that you are using the currently focused cmux context.
除非用户明确指定其他工作区、窗口或全局状态，否则将操作范围限定在当前调用方工作区内。
不要假设视觉上处于焦点的cmux工作区就是正确的目标。Agent可能在一个工作区运行，而用户正在查看另一个工作区。优先以调用方环境为准：
bash
printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" \
  "${CMUX_SURFACE_ID:-}" \
  "${CMUX_SOCKET_PATH:-}"
cmux identify --json
将
CMUX_WORKSPACE_ID
作为默认工作区锚点，
CMUX_SURFACE_ID
作为默认调用方终端/界面锚点。如果这些变量不存在，使用
cmux identify --json
，并明确说明你正在使用当前处于焦点的cmux上下文。

Non-Disruptive Automation

无干扰自动化

The user may be visually focused on a different workspace, window, or app while an agent works in the caller workspace. Treat layout and focus as separate concerns. Never call focus-changing verbs speculatively.
Never call these without an explicit user ask:
  • select-workspace
    switches the visible sidebar tab.
  • focus-pane
    / 
    focus-panel
    yanks pane or surface focus.
  • tab-action
    with focus-changing actions.
These are user-affecting actions, like clicks. The rule applies even inside the caller's own workspace, since the user may be looking elsewhere.
Build layout additively, in one shot. Prefer commands that create a new pane already populated with the right surface:
bash
undefined
当Agent在调用方工作区内工作时，用户可能正将视觉焦点放在其他工作区、窗口或应用上。将布局调整与焦点控制视为独立事项。切勿随意调用改变焦点的操作。
除非用户明确要求，否则不要调用以下操作：
  • select-workspace
    ：切换可见的侧边栏标签。
  • focus-pane
    / 
    focus-panel
    ：抢占窗格或界面的焦点。
  • 带有焦点变更操作的
    tab-action
    。
这些操作会影响用户体验，就像直接点击一样。即使在调用方自己的工作区内，该规则同样适用，因为用户可能正在查看其他地方。
一次性完成布局的增量构建。优先使用能直接创建包含正确界面的新窗格的命令：
bash
undefined

pane and content in one call, no follow-up needed

一次调用完成窗格创建与内容填充，无需后续操作

cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type browser --direction right --url "http://127.0.0.1:8765" cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type terminal --direction down

Avoid create-then-move-then-focus chains. If a layout command rejects a valid `surface:` or `pane:` ref, do not work around it by focusing. Report the bug to the user and stop.

Pass `--focus false` whenever the verb supports it. `move-surface --focus false` preserves the user's current attention. Other commands may grow the same flag over time (https://github.com/manaflow-ai/cmux/issues/1418, https://github.com/manaflow-ai/cmux/issues/2820).
cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type browser --direction right --url "http://127.0.0.1:8765" cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type terminal --direction down

避免使用“创建-移动-聚焦”的操作链。如果布局命令拒绝了有效的`surface:`或`pane:`引用，不要通过聚焦来解决问题。将该错误报告给用户并停止操作。

只要操作支持，就传递`--focus false`参数。`move-surface --focus false`可以保持用户当前的注意力焦点。未来其他命令也可能添加相同的参数（https://github.com/manaflow-ai/cmux/issues/1418, https://github.com/manaflow-ai/cmux/issues/2820）。

Right-Side Helper Pane

右侧辅助窗格

When opening auxiliary output for the current task (preview apps, TUIs, logs, one-off shells, browser checks), keep the workspace organized by reusing a helper pane to the right of the caller terminal.
First inspect the caller context and panes:
bash
cmux identify --json
cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
Use this policy:
  • If the caller workspace already has a non-caller helper pane, add a new surface to that pane instead of creating another pane:
    bash
    cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:<helper> --type terminal --focus false
  • If there is no helper pane, create exactly one right-side pane:
    bash
    cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false
  • If there are multiple obvious stale helper panes from this same automation and the user asked to tidy or reuse, keep one right helper pane and clean up the duplicates. Do not close panes you cannot confidently identify as stale helper output.
  • Send commands to the new or reused helper surface by explicit surface ref. Do not focus it unless the user asks.
This means repeated "open it" requests should normally create tabs inside the existing right helper pane, not more splits.
当为当前任务打开辅助输出（预览应用、TUI、日志、临时Shell、浏览器检查）时，通过复用调用方终端右侧的辅助窗格来保持工作区整洁。
首先检查调用方上下文和窗格：
bash
cmux identify --json
cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
遵循以下策略：
  • 如果调用方工作区已有非调用方的辅助窗格，在该窗格中添加新界面，而非创建新窗格：
    bash
    cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:<helper> --type terminal --focus false
  • 如果没有辅助窗格，仅创建一个右侧窗格：
    bash
    cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false
  • 如果存在多个由同一自动化流程生成的明显过时的辅助窗格，且用户要求整理或复用，则保留一个右侧辅助窗格并清理重复项。不要关闭无法确定为过时辅助输出的窗格。
  • 通过明确的界面引用向新创建或复用的辅助界面发送命令。除非用户要求，否则不要聚焦它。
这意味着重复的“打开”请求通常应在现有右侧辅助窗格内创建标签页，而非新增拆分窗格。

Hierarchy

层级结构

  • Window: a macOS cmux window.
  • Workspace: a sidebar entry. The UI may call it a tab, but CLI/socket APIs call it a workspace.
  • Pane: a split region inside a workspace.
  • Surface: a tab inside a pane. Surfaces can be terminals or browser panels.
  • Panel: internal content type inside a surface. Prefer CLI surface commands instead of panel internals.
  • Window：macOS系统中的cmux窗口。
  • Workspace：侧边栏条目。UI中可能称为标签页，但CLI/套接字API中称为工作区。
  • Pane：工作区内的拆分区域。
  • Surface：窗格内的标签页。界面可以是终端或浏览器面板。
  • Panel：界面内部的内容类型。优先使用CLI界面命令，而非面板内部操作。

Inspect Current Context

检查当前上下文

bash
cmux identify --json
cmux current-workspace --json
cmux list-workspaces --json
cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-panels --workspace "${CMUX_WORKSPACE_ID:-}" --json
Use 
--id-format both
when logs or handoffs need stable UUIDs plus human refs:
bash
cmux --json --id-format both identify
bash
cmux identify --json
cmux current-workspace --json
cmux list-workspaces --json
cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-panels --workspace "${CMUX_WORKSPACE_ID:-}" --json
当日志或交接需要稳定UUID和易读引用时，使用
--id-format both
参数：
bash
cmux --json --id-format both identify

Workspace-Scoped Actions

工作区范围的操作

Prefer explicit workspace flags even when env vars are set. It makes automation auditable and avoids affecting a focused workspace in another window.
bash
undefined
即使已设置环境变量，也优先使用明确的工作区参数。这会让自动化流程可审计，并避免影响其他窗口中处于焦点的工作区。
bash
undefined

create a new workspace when the user asks for a new task area

当用户要求新的任务区域时，创建新工作区

cmux new-workspace --name "debug auth" --cwd "$PWD"
cmux new-workspace --name "debug auth" --cwd "$PWD"

rename / close (only when explicitly requested)

重命名 / 关闭（仅在明确请求时执行）

cmux rename-workspace --workspace "${CMUX_WORKSPACE_ID:-}" -- "build fix" cmux close-workspace --workspace workspace:4 cmux close-surface --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:3
cmux rename-workspace --workspace "${CMUX_WORKSPACE_ID:-}" -- "build fix" cmux close-workspace --workspace workspace:4 cmux close-surface --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:3

additive layout (safe, no focus side effects beyond the command's own defaults)

增量布局（安全，除命令自身默认行为外无焦点副作用）

cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal
cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal

focus-changing (USER-AFFECTING, only on explicit ask, see Non-Disruptive Automation above)

变更焦点（影响用户体验，仅在明确请求时执行，详见上文无干扰自动化部分）

cmux select-workspace --workspace workspace:2 cmux focus-pane --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2 cmux focus-panel --workspace "${CMUX_WORKSPACE_ID:-}" --panel surface:3
undefined
cmux select-workspace --workspace workspace:2 cmux focus-pane --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2 cmux focus-panel --workspace "${CMUX_WORKSPACE_ID:-}" --panel surface:3
undefined

Caller Terminal

调用方终端

The current terminal is the surface that invoked the agent. Treat it as the safest anchor for relative operations.
bash
undefined
当前终端是调用Agent的界面。将其视为相对操作最安全的锚点。
bash
undefined

send to the focused terminal in the caller workspace

发送到调用方工作区内处于焦点的终端

cmux send "npm test\n"
cmux send "npm test\n"

send to the exact caller surface

发送到确切的调用方界面

cmux send --surface "${CMUX_SURFACE_ID:-}" "git status\n" cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter

Do not send keystrokes, close surfaces, or change focus in other workspaces unless the user asked for that target.
cmux send --surface "${CMUX_SURFACE_ID:-}" "git status\n" cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter

除非用户指定目标，否则不要向其他工作区发送按键指令、关闭界面或变更焦点。

Moving Surfaces

移动界面

Reorder a surface within its pane:
bash
cmux move-surface --surface "${CMUX_SURFACE_ID}" --before surface:3
cmux move-surface --surface "${CMUX_SURFACE_ID}" --after surface:3
cmux move-surface --surface "${CMUX_SURFACE_ID}" --index 0
Move a surface to another existing pane. Pass 
--focus false
to keep the user's current attention put:
bash
cmux move-surface --surface surface:240 --pane pane:172 --focus false
Split a surface off into a new pane:
bash
cmux drag-surface-to-split --surface surface:240 down
Known papercut: 
drag-surface-to-split
currently routes through V1 and resolves the workspace via UI focus, so it can fail with 
ERROR: Surface not found
when the caller's workspace is not the visually focused one. Tracked at https://github.com/manaflow-ai/cmux/issues/1901, related to https://github.com/manaflow-ai/cmux/issues/3189. Until that lands, prefer building the layout additively (see Non-Disruptive Automation above) over create-then-split.
Do not call 
focus-pane
or 
focus-panel
to recover from a failed move. Report the failure and stop.
在窗格内重新排序界面：
bash
cmux move-surface --surface "${CMUX_SURFACE_ID}" --before surface:3
cmux move-surface --surface "${CMUX_SURFACE_ID}" --after surface:3
cmux move-surface --surface "${CMUX_SURFACE_ID}" --index 0
将界面移动到另一个已存在的窗格。传递
--focus false
参数以保持用户当前的注意力焦点：
bash
cmux move-surface --surface surface:240 --pane pane:172 --focus false
将界面拆分到新窗格：
bash
cmux drag-surface-to-split --surface surface:240 down
已知问题：
drag-surface-to-split
当前通过V1路由，并通过UI焦点解析工作区，因此当调用方工作区并非视觉焦点时，可能会出现
ERROR: Surface not found
错误。相关问题跟踪：https://github.com/manaflow-ai/cmux/issues/1901，关联问题：https://github.com/manaflow-ai/cmux/issues/3189。在该问题修复前，优先使用增量方式构建布局（详见上文无干扰自动化部分），而非“创建-拆分”的操作链。
不要调用
focus-pane
或
focus-panel
来恢复移动失败的情况。报告失败并停止操作。

Sidebar State

侧边栏状态

Status, progress, and logs should usually be attached to the current workspace so the sidebar reflects this task.
bash
cmux set-status build "running" --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"
cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- "Started build"
cmux sidebar-state --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux clear-status build --workspace "${CMUX_WORKSPACE_ID:-}"
cmux clear-progress --workspace "${CMUX_WORKSPACE_ID:-}"
状态、进度和日志通常应附加到当前工作区，以便侧边栏能反映任务状态。
bash
cmux set-status build "running" --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"
cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- "Started build"
cmux sidebar-state --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux clear-status build --workspace "${CMUX_WORKSPACE_ID:-}"
cmux clear-progress --workspace "${CMUX_WORKSPACE_ID:-}"

Contributor Reloads

贡献者重载

For cmux app/runtime changes in a cmux source checkout, use tagged reloads from the active worktree. A tagged reload creates an isolated app name, bundle ID, debug socket, and DerivedData path.
bash
./scripts/reload.sh --tag <short-tag>
Never build or launch untagged 
cmux DEV
. If tests or tools need a socket, use the tag-specific socket:
bash
CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux identify --json
在cmux源码 checkout 中修改cmux应用/运行时后，使用活动工作树中的标记重载。标记重载会创建独立的应用名称、Bundle ID、调试套接字和DerivedData路径。
bash
./scripts/reload.sh --tag <short-tag>
永远不要构建或启动未标记的
cmux DEV
。如果测试或工具需要套接字，使用标记特定的套接字：
bash
CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux identify --json

Socket and Access

套接字与访问权限

Use the socket path provided by cmux before falling back to defaults:
bash
SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"
Socket access can be off, restricted to cmux-spawned processes, or allow all local processes. If a command cannot connect, inspect capabilities before changing settings:
bash
cmux capabilities --json
cmux ping
优先使用cmux提供的套接字路径，再回退到默认路径：
bash
SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"
套接字访问权限可能关闭、仅限cmux启动的进程，或允许所有本地进程。如果命令无法连接，在更改设置前先检查权限：
bash
cmux capabilities --json
cmux ping

References

参考资料

  • references/commands.md enumerates workspace, pane, surface, notification, and utility commands.
  • ../cmux-browser/SKILL.md covers browser surfaces with the same current-workspace rule.
  • references/commands.md 列举了工作区、窗格、界面、通知和实用工具命令。
  • ../cmux-browser/SKILL.md 涵盖了浏览器界面的相关内容，遵循相同的当前工作区规则。

Rules

规则总结

  • Work in the current caller workspace by default.
  • Use 
    CMUX_WORKSPACE_ID
    , 
    CMUX_SURFACE_ID
    , and 
    CMUX_SOCKET_PATH
    before focused-window fallbacks.
  • Prefer explicit 
    --workspace
    and 
    --surface
    flags for mutating actions.
  • Never call 
    focus-pane
    , 
    focus-panel
    , 
    select-workspace
    , or focus-changing 
    tab-action
    verbs unless the user explicitly asked. The user may be visually on a different workspace, window, or app.
  • Pass 
    --focus false
    on 
    move-surface
    and any creation verb that supports it.
  • For auxiliary output, reuse the right-side helper pane; create one only if it does not exist.
  • Build layout additively with 
    new-pane --type ... --url ...
    rather than create-then-move-then-focus chains.
  • If a CLI command rejects a valid surface or pane ref, report it to the user. Do not work around by focusing.
  • Do not close, focus, move, or send input to another workspace unless the user names that target.
  • Use short refs for chat and command examples. Use UUIDs only for logs, persistence, or debugging.
  • For app/runtime changes in a cmux source checkout, reload with 
    ./scripts/reload.sh --tag <tag>
    from the worktree before dogfood handoff.
  • 默认在当前调用方工作区内操作。
  • 优先使用
    CMUX_WORKSPACE_ID
    、
    CMUX_SURFACE_ID
    和
    CMUX_SOCKET_PATH
    ，再回退到焦点窗口。
  • 对于变更类操作，优先使用明确的
    --workspace
    和
    --surface
    参数。
  • 除非用户明确要求，否则不要调用
    focus-pane
    、
    focus-panel
    、
    select-workspace
    或带有焦点变更的
    tab-action
    操作。用户可能正将视觉焦点放在其他工作区、窗口或应用上。
  • 在
    move-surface
    和任何支持的创建类操作中传递
    --focus false
    参数。
  • 对于辅助输出，复用右侧辅助窗格；仅在不存在时创建一个。
  • 使用
    new-pane --type ... --url ...
    增量构建布局，而非“创建-移动-聚焦”的操作链。
  • 如果CLI命令拒绝了有效的界面或窗格引用，将其报告给用户。不要通过聚焦来解决问题。
  • 除非用户指定目标，否则不要关闭、聚焦、移动其他工作区的内容，或向其发送输入。
  • 在聊天和命令示例中使用短引用。仅在日志、持久化或调试时使用UUID。
  • 在cmux源码 checkout 中修改应用/运行时后，在内部测试前使用工作树中的
    ./scripts/reload.sh --tag <tag>
    进行重载。