Back to Details

cmux

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cmux Orchestration

cmux 终端编排

Orchestrate terminal sessions, spawn Claude Code instances, automate the built-in browser, preview markdown — all inside cmux.
在cmux中编排终端会话、启动Claude Code实例、自动化内置浏览器、预览Markdown。

Detection

环境检测

Check 
CMUX_WORKSPACE_ID
env var. If set → you're in cmux. If unset → skip all cmux commands.
Auto-set env vars: 
CMUX_WORKSPACE_ID
, 
CMUX_SURFACE_ID
, 
CMUX_SOCKET_PATH
.
检查环境变量
CMUX_WORKSPACE_ID
。如果已设置 → 你处于cmux环境中。如果未设置 → 跳过所有cmux命令。
自动设置的环境变量：
CMUX_WORKSPACE_ID
、
CMUX_SURFACE_ID
、
CMUX_SOCKET_PATH
。

Hierarchy

层级结构

Window > Workspace (sidebar tab) > Pane (split region) > Surface (terminal tab in pane).
Short refs: 
workspace:1
, 
pane:1
, 
surface:2
.
窗口 > 工作区（侧边栏标签） > 面板（拆分区域） > 界面（面板中的终端标签）。
简短引用：
workspace:1
、
pane:1
、
surface:2
。

Orientation

查看环境信息

bash
cmux identify --json                              # your current context
cmux list-workspaces                              # all workspaces
cmux list-panes                                   # panes in current workspace
cmux list-pane-surfaces --pane <ref>              # surfaces in a pane
cmux tree --all                                   # full hierarchy view
cmux trigger-flash --surface <ref>               # flash surface for visual confirmation
cmux surface-health                               # detect hidden/detached surfaces
bash
cmux identify --json                              # 获取当前上下文信息
cmux list-workspaces                              # 列出所有工作区
cmux list-panes                                   # 列出当前工作区中的所有面板
cmux list-pane-surfaces --pane <ref>              # 列出指定面板中的界面
cmux tree --all                                   # 查看完整层级结构
cmux trigger-flash --surface <ref>               # 闪烁指定界面以进行视觉确认
cmux surface-health                               # 检测隐藏/分离的界面

Create Terminals

创建终端

bash
cmux new-split <left|right|up|down>               # split current pane
cmux new-workspace --cwd <path>                   # new workspace tab
cmux new-surface                                  # new tab in current pane
bash
cmux new-split <left|right|up|down>               # 拆分当前面板
cmux new-workspace --cwd <path>                   # 创建新工作区标签
cmux new-surface                                  # 在当前面板中创建新标签

Launch Agents in a Pane

在面板中启动Agent

Network access requires proxy env vars. Always set them before agent commands.
Important: When sending compound commands (proxy export + agent launch), send them as a single string to 
cmux send
. Do NOT split into separate 
send
calls — the second command would run before the first finishes.
bash
undefined
网络访问需要代理环境变量。启动Agent命令前务必设置代理变量。
重要提示：发送复合命令（代理变量导出 + Agent启动）时，需将其作为单个字符串发送给
cmux send
。请勿拆分为多个
send
调用——第二个命令会在第一个命令完成前执行。
bash
undefined

Claude Code — interactive mode (user can switch to this pane and intervene)

Claude Code — 交互模式（用户可切换到该面板进行干预）

cmux send --surface <ref> 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && claude --dangerously-skip-permissions\n'
cmux send --surface <ref> 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && claude --dangerously-skip-permissions\n'

Claude Code — non-interactive mode (run task, capture output, signal completion)

Claude Code — 非交互模式（运行任务、捕获输出、发送完成信号）

cmux send --surface <ref> 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && claude -p "your prompt" --model haiku 2>&1 | tee /tmp/agent-output.txt; echo "AGENT_DONE"\n'
cmux send --surface <ref> 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && claude -p "your prompt" --model haiku 2>&1 | tee /tmp/agent-output.txt; echo "AGENT_DONE"\n'

Codex — interactive mode (full-auto, user can intervene)

Codex — 交互模式（全自动，用户可干预）

cmux send --surface <ref> 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && codex --dangerously-bypass-approvals-and-sandbox\n'
cmux send --surface <ref> 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && codex --dangerously-bypass-approvals-and-sandbox\n'

Codex — with initial prompt

Codex — 带初始提示词

cmux send --surface <ref> 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && codex --dangerously-bypass-approvals-and-sandbox -p "your prompt"\n'

When the user asks to "split a pane with Codex/Claude/agent", always:
1. `cmux new-split <direction>` to create the pane
2. `cmux send --surface <new-ref> '<export https_proxy=... && agent command>\n'` to launch
3. Optionally send context after the agent starts: `cmux send --surface <new-ref> 'prompt'` then `cmux send-key --surface <new-ref> enter`
cmux send --surface <ref> 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && codex --dangerously-bypass-approvals-and-sandbox -p "your prompt"\n'

当用户要求“用Codex/Claude/Agent拆分面板”时，需执行以下步骤：
1. 使用`cmux new-split <direction>`创建面板
2. 使用`cmux send --surface <new-ref> '<export https_proxy=... && agent command>\n'`启动Agent
3. 可选：Agent启动后发送上下文信息：`cmux send --surface <new-ref> 'prompt'`，然后执行`cmux send-key --surface <new-ref> enter`

Send Input / Read Output

发送输入 / 读取输出

bash
cmux send --surface <ref> 'text\n'                # send text + Enter (for shell commands)
cmux send --surface <ref> 'text'                  # send text only (no Enter)
cmux send-key --surface <ref> <key>               # send special key (ctrl-c, enter, etc.)
cmux read-screen --surface <ref> --lines <n>      # read last n lines of terminal output
Shell vs interactive programs: 
\n
works as Enter for shell prompts (bash processes it via line discipline). But interactive programs in raw terminal mode (Claude Code, vim, etc.) treat 
\n
as a literal newline character, not a submit action. For those, send text without 
\n
, then use 
send-key enter
:
bash
undefined
bash
cmux send --surface <ref> 'text\n'                # 发送文本并按下回车（适用于Shell命令）
cmux send --surface <ref> 'text'                  # 仅发送文本（不按回车）
cmux send-key --surface <ref> <key>               # 发送特殊按键（ctrl-c、回车等）
cmux read-screen --surface <ref> --lines <n>      # 读取终端最后n行输出
Shell与交互程序的区别：对于Shell提示符，
\n
相当于回车（Bash通过行规则处理）。但对于处于原始终端模式的交互程序（Claude Code、vim等），
\n
会被视为字面意义上的换行符，而非提交操作。对于这类程序，需先发送不带
\n
的文本，再使用
send-key enter
：
bash
undefined

Shell command — \n works as Enter

Shell命令 — \n等效于回车

cmux send --surface <ref> 'ls -la\n'
cmux send --surface <ref> 'ls -la\n'

Interactive program — use send-key enter to submit

交互程序 — 使用send-key enter提交

cmux send --surface <ref> 'your message here' cmux send-key --surface <ref> enter
undefined
cmux send --surface <ref> 'your message here' cmux send-key --surface <ref> enter
undefined

Sidebar Status & Progress

侧边栏状态与进度

The sidebar is always visible — use it to give the user a glance at what's happening without switching panes.
bash
cmux set-status <key> <value> --icon <name> --color <#hex>
cmux set-progress <0.0-1.0> --label "text"
cmux log --level <info|success|warning|error> --source "agent" -- "message"
cmux notify --title "Title" --body "Body"         # desktop notification
cmux clear-status <key> / cmux clear-progress / cmux clear-log
侧边栏始终可见——可通过它让用户无需切换面板即可快速了解当前状态。
bash
cmux set-status <key> <value> --icon <name> --color <#hex>
cmux set-progress <0.0-1.0> --label "text"
cmux log --level <info|success|warning|error> --source "agent" -- "message"
cmux notify --title "Title" --body "Body"         # 桌面通知
cmux clear-status <key> / cmux clear-progress / cmux clear-log

Workspace Management

工作区管理

bash
cmux rename-workspace "name"
cmux rename-tab --surface <ref> "name"
cmux close-surface --surface <ref>
cmux close-workspace --workspace <ref>
bash
cmux rename-workspace "name"
cmux rename-tab --surface <ref> "name"
cmux close-surface --surface <ref>
cmux close-workspace --workspace <ref>

Browser (quick reference)

浏览器（快速参考）

Open sites in cmux's built-in browser, interact with pages, take screenshots. Read references/browser.md for full command reference, form automation, and troubleshooting.
bash
cmux --json browser open https://example.com      # open browser split, returns surface ref
cmux browser <surface> wait --load-state complete --timeout-ms 15000
cmux browser <surface> snapshot --interactive      # get clickable element refs
cmux browser <surface> click e1                    # click element by ref
cmux browser <surface> fill e2 "text"              # fill input field
cmux browser <surface> screenshot --out /tmp/s.png # take screenshot
cmux browser <surface> get url                     # current URL
cmux browser <surface> get title                   # page title
cmux browser <surface> navigate <url>              # go to URL
在cmux内置浏览器中打开网站、与页面交互、截图。完整命令参考、表单自动化及故障排除请查看references/browser.md。
bash
cmux --json browser open https://example.com      # 打开浏览器拆分面板，返回界面引用
cmux browser <surface> wait --load-state complete --timeout-ms 15000
cmux browser <surface> snapshot --interactive      # 获取可点击元素引用
cmux browser <surface> click e1                    # 通过引用点击元素
cmux browser <surface> fill e2 "text"              # 填充输入框
cmux browser <surface> screenshot --out /tmp/s.png # 截图
cmux browser <surface> get url                     # 获取当前URL
cmux browser <surface> get title                   # 获取页面标题
cmux browser <surface> navigate <url>              # 导航到指定URL

Markdown Preview (quick reference)

Markdown预览（快速参考）

Display formatted markdown alongside the terminal with live reload. Read references/markdown.md for routing options and agent integration patterns.
bash
cmux markdown open plan.md                         # open preview panel (auto-reloads on file change)
cmux markdown open plan.md --workspace workspace:2 # target specific workspace
在终端旁显示格式化的Markdown并支持实时重载。路由选项及Agent集成模式请查看references/markdown.md。
bash
cmux markdown open plan.md                         # 打开预览面板（文件变更时自动重载）
cmux markdown open plan.md --workspace workspace:2 # 目标指定工作区

Workflow Patterns

工作流模式

Fan out into splits (parallel tasks)

拆分面板分发任务（并行任务）

bash
cmux new-split right
cmux send --surface surface:2 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && claude -p "analyze project structure" --model haiku > /tmp/a1.txt; echo "DONE"\n'

cmux new-split down
cmux send --surface surface:3 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && claude -p "count code lines" --model haiku > /tmp/a2.txt; echo "DONE"\n'

cmux set-status task "Running" --icon hammer --color "#1565C0"
bash
cmux new-split right
cmux send --surface surface:2 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && claude -p "analyze project structure" --model haiku > /tmp/a1.txt; echo "DONE"\n'

cmux new-split down
cmux send --surface surface:3 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && claude -p "count code lines" --model haiku > /tmp/a2.txt; echo "DONE"\n'

cmux set-status task "Running" --icon hammer --color "#1565C0"

Poll: cmux read-screen --surface surface:2 --lines 5

轮询：cmux read-screen --surface surface:2 --lines 5

Collect: cat /tmp/a1.txt /tmp/a2.txt

收集结果：cat /tmp/a1.txt /tmp/a2.txt

Clean up: cmux close-surface --surface surface:2 && cmux close-surface --surface surface:3

清理：cmux close-surface --surface surface:2 && cmux close-surface --surface surface:3

undefined
undefined

Interactive sub-agents (user can intervene)

交互式子Agent（用户可干预）

Launch an agent in a split pane that the user can interact with directly:
bash
undefined
在拆分面板中启动用户可直接交互的Agent：
bash
undefined

Claude Code in right split

在右侧拆分面板中启动Claude Code

cmux new-split right cmux send --surface surface:2 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && claude --dangerously-skip-permissions\n'
cmux new-split right cmux send --surface surface:2 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && claude --dangerously-skip-permissions\n'

Codex in right split (full-auto mode)

在右侧拆分面板中启动Codex（全自动模式）

cmux new-split right cmux send --surface surface:2 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && codex --dangerously-bypass-approvals-and-sandbox\n'

To feed context to the agent after it starts (e.g., a handoff prompt):
```bash
cmux new-split right cmux send --surface surface:2 'export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890 && codex --dangerously-bypass-approvals-and-sandbox\n'

Agent启动后，如需向其发送上下文信息（例如交接提示词）：
```bash

Wait for the agent to be ready, then send context

等待Agent准备就绪，然后发送上下文

sleep 5 cmux send --surface surface:2 'Here is the task: ...' cmux send-key --surface surface:2 enter

User can press `⌥⌘→` to switch to the agent pane and talk to it directly.
sleep 5 cmux send --surface surface:2 'Here is the task: ...' cmux send-key --surface surface:2 enter

用户可按`⌥⌘→`切换到Agent面板直接与其交互。

Progress tracking

进度跟踪

bash
cmux set-progress 0.0 --label "Starting"
bash
cmux set-progress 0.0 --label "Starting"

... work ...

... 执行任务 ...

cmux set-progress 0.5 --label "Testing"
cmux set-progress 0.5 --label "Testing"

... work ...

... 执行任务 ...

cmux set-progress 1.0 --label "Complete" cmux clear-progress cmux notify --title "Done" --body "All tasks finished"
undefined
cmux set-progress 1.0 --label "Complete" cmux clear-progress cmux notify --title "Done" --body "All tasks finished"
undefined

Safety Rules

安全规则

  • Don't send to surfaces you didn't create — the user may be actively typing there.
  • Always target by surface ref — use 
    --surface <ref>
    from when you created the pane.
  • Don't steal focus — avoid 
    select-workspace
    , 
    focus-pane
    unless the user asked.
  • Clean up after yourself — close surfaces/workspaces you created once done.
  • Start with 
    identify --json
     — know your context before creating terminals.
  • 不要向非你创建的界面发送内容—— пользователь可能正在该界面输入内容。
  • 始终通过界面引用指定目标——使用创建面板时获取的
    --surface <ref>
    。
  • 不要抢占焦点——除非用户要求，否则避免使用
    select-workspace
    、
    focus-pane
    。
  • 完成后清理资源——关闭你创建的界面/工作区。
  • 先执行
    identify --json
    ——创建终端前先了解当前上下文。