cmux-customize

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cmux-customize

Use this skill for personal cmux configuration changes stored outside the app source tree, especially

~/.config/cmux/cmux.json

and project-local

.cmux/cmux.json

files. It covers action registry entries, surface tab bar buttons, plus-button click and right-click menu behavior, custom workspace commands, right sidebar wiring, and related config cleanup.

使用此技能对存储在应用源代码树之外的个人cmux配置进行修改，尤其是

~/.config/cmux/cmux.json

和项目本地的

.cmux/cmux.json

文件。它涵盖操作注册表条目、界面标签栏按钮、加号按钮点击及右键菜单行为、自定义工作区命令、右侧边栏配置，以及相关配置清理。

Prerequisites

前提条件

Use the
```
cmux-settings
```
skill's
```
cmux-settings
```
helper script for global
```
~/.config/cmux/cmux.json
```
reads and writes.

Read the

cmux-settings

skill first when the task touches standard settings under

app

terminal

notifications

sidebar

sidebarAppearance

workspaceColors

automation

browser

, or

shortcuts

使用
```
cmux-settings
```
技能的
```
cmux-settings
```
辅助脚本对全局
```
~/.config/cmux/cmux.json
```
进行读写操作。

当任务涉及

app

、

terminal

、

notifications

、

sidebar

、

sidebarAppearance

、

workspaceColors

、

automation

、

browser

或

shortcuts

下的标准设置时，请先查阅

cmux-settings

技能。

Reference

参考信息

Global config:

bash

cmux-settings path
cmux-settings dump --no-comments

Common structural sections in

cmux.json

```
actions
```
: action registry used by custom UI and commands.
```
ui.surfaceTabBar.buttons
```
: buttons shown in the surface tab bar.
```
ui.newWorkspace.action
```
: action triggered by a normal click on the plus button.
```
ui.newWorkspace.contextMenu
```
: menu items shown when right-clicking the plus button.
```
commands
```
: named workspace commands and layouts.
```
rightSidebar
```
: custom right sidebar wiring.
```
vault
```
: custom Vault agent registrations.

ui.surfaceTabBar.buttons

can contain built-in action ids as strings or object references:

json

[
  "cmux.newTerminal",
  "cmux.newBrowser",
  "cmux.splitRight",
  "cmux.splitDown",
  { "action": "custom-action-id" }
]

Use

ui.newWorkspace.contextMenu

for plus-button right-click menus.

ui.newWorkspace.rightClick

is accepted by cmux as a legacy alias, but new edits should use

contextMenu

全局配置：

bash

cmux-settings path
cmux-settings dump --no-comments

cmux.json

中的常见结构部分：

```
actions
```
：自定义UI和命令使用的操作注册表。
```
ui.surfaceTabBar.buttons
```
：界面标签栏中显示的按钮。
```
ui.newWorkspace.action
```
：点击加号按钮时触发的操作。
```
ui.newWorkspace.contextMenu
```
：右键点击加号按钮时显示的菜单项。
```
commands
```
：命名的工作区命令和布局。
```
rightSidebar
```
：自定义右侧边栏配置。
```
vault
```
：自定义Vault agent注册项。

ui.surfaceTabBar.buttons

可以包含字符串形式的内置操作ID或对象引用：

json

[
  "cmux.newTerminal",
  "cmux.newBrowser",
  "cmux.splitRight",
  "cmux.splitDown",
  { "action": "custom-action-id" }
]

使用

ui.newWorkspace.contextMenu

配置加号按钮的右键菜单。cmux接受

ui.newWorkspace.rightClick

作为旧版别名，但新编辑应使用

contextMenu

。

Workflow

工作流程

Step 1: Inspect current config

步骤1：检查当前配置

Read the existing config before changing anything.

bash

cmux-settings dump --no-comments

If the user names a visible UI surface, search for the related ids.

bash

rg -n "surfaceTabBar|newWorkspace|rightSidebar|<action-id>|<label>" ~/.config/cmux/cmux.json

在进行任何修改前，先读取现有配置。

bash

cmux-settings dump --no-comments

如果用户指定了某个可见的UI界面，搜索相关ID。

bash

rg -n "surfaceTabBar|newWorkspace|rightSidebar|<action-id>|<label>" ~/.config/cmux/cmux.json

Step 2: Make the smallest config edit

步骤2：进行最小化配置编辑

Use the helper for global config edits. It parses JSONC and writes atomically.

Remove custom agent launch buttons from the surface tab bar while keeping built-in surface controls:

bash

cmux-settings set ui.surfaceTabBar.buttons \
  '["cmux.newTerminal","cmux.newBrowser","cmux.splitRight","cmux.splitDown"]'

Remove one named action from a tab bar without deleting the action registry entry:

bash

cmux-settings get ui.surfaceTabBar.buttons

使用辅助脚本进行全局配置编辑。它会解析JSONC并以原子方式写入。

从界面标签栏中移除自定义agent启动按钮，同时保留内置界面控件：

bash

cmux-settings set ui.surfaceTabBar.buttons \
  '["cmux.newTerminal","cmux.newBrowser","cmux.splitRight","cmux.splitDown"]'

从标签栏中移除一个指定操作，但不删除操作注册表条目：

bash

cmux-settings get ui.surfaceTabBar.buttons

Edit the array to remove only { "action": "<action-id>" }, then set it back.

编辑数组以仅移除 { "action": "<action-id>" }，然后重新设置。


Delete an action entirely only when the user asks for the command itself to go away from every surface.

```bash
cmux-settings unset actions.<action-id>

Customize the plus button and its right-click menu:

bash

cmux-settings set ui.newWorkspace.action '"workspace-new-cmux-worktree"'
cmux-settings set ui.newWorkspace.contextMenu \
  '[{"action":"workspace-new-cmux-worktree","title":"New cmux Worktree"},{"action":"workspace-terminal-browser","title":"Terminal + Browser"},{"type":"separator"},{"action":"cmux.newTerminal","title":"New Terminal"},{"action":"cmux.newBrowser","title":"New Browser"}]'


仅当用户要求该命令从所有界面中移除时，才完全删除操作。

```bash
cmux-settings unset actions.<action-id>

自定义加号按钮及其右键菜单：

bash

cmux-settings set ui.newWorkspace.action '"workspace-new-cmux-worktree"'
cmux-settings set ui.newWorkspace.contextMenu \
  '[{"action":"workspace-new-cmux-worktree","title":"New cmux Worktree"},{"action":"workspace-terminal-browser","title":"Terminal + Browser"},{"type":"separator"},{"action":"cmux.newTerminal","title":"New Terminal"},{"action":"cmux.newBrowser","title":"New Browser"}]'

Step 3: Verify

步骤3：验证

Always read back the changed path.

bash

cmux-settings get ui.surfaceTabBar.buttons
cmux-settings get ui.newWorkspace.contextMenu

Validate parseability. The strict supported-key validator may flag valid structural or newer app keys when the checked-out source list is older than the running app. If that happens, do not remove unrelated keys. Confirm the file parses and report the unrelated validator warning.

bash

cmux-settings dump --no-comments >/tmp/cmux-config.json

始终读取修改后的路径。

bash

cmux-settings get ui.surfaceTabBar.buttons
cmux-settings get ui.newWorkspace.contextMenu

验证可解析性。当检出的源列表版本早于运行的应用版本时，严格的支持键验证器可能会标记有效的结构键或较新的应用键。如果发生这种情况，请勿删除无关键。确认文件可解析并报告无关的验证器警告。

bash

cmux-settings dump --no-comments >/tmp/cmux-config.json

Step 4: Report apply behavior

步骤4：报告应用行为

cmux watches

~/.config/cmux/cmux.json

, so config edits apply after save without a rebuild. Do not run a tagged app reload for pure config or skill changes.

cmux会监听

~/.config/cmux/cmux.json

，因此配置编辑保存后无需重建即可生效。对于纯配置或技能更改，无需运行标记的应用重新加载。

Rules

规则

Preserve unrelated custom actions, commands, menus, Vault entries, and right sidebar config.
Do not delete action definitions just because their buttons were removed from the tab bar.
Do not use
```
defaults write
```
for persistent product config.
Do not edit
```
repo/
```
for user config changes.
Do not run app reloads for config-only or skill-only changes.
Keep responses short and include the exact path or key changed.

保留无关的自定义操作、命令、菜单、Vault条目和右侧边栏配置。
不要仅因为操作按钮从标签栏中移除就删除操作定义。
不要使用
```
defaults write
```
进行持久化产品配置。
不要编辑
```
repo/
```
目录来更改用户配置。
不要针对仅配置或仅技能更改运行应用重新加载。
保持回复简洁，并包含更改的确切路径或键。