cmux-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cmux-config

Single entry point for editing a user's cmux configuration in

~/.config/cmux/cmux.json

(JSONC). The app watches the file; saving applies changes immediately, no restart. Legacy

~/.config/cmux/settings.json

is read only as a fallback for keys absent from

cmux.json

Three areas, each with a reference:

Settings — typed preferences under
```
app
```
,
```
terminal
```
,
```
notifications
```
,
```
sidebar
```
,
```
sidebarAppearance
```
,
```
workspaceColors
```
,
```
automation
```
,
```
browser
```
,
```
shortcuts
```
. See the helper below and references/all-keys.md / references/shortcut-actions.md.
Customization — structural config:
```
actions
```
,
```
ui.surfaceTabBar.buttons
```
,
```
ui.newWorkspace
```
(plus-button click + context menu),
```
commands
```
,
```
rightSidebar
```
,
```
vault
```
. See references/customize.md.
Workspace groups — collapsible anchor-owned sidebar sections via the
```
cmux workspace group
```
CLI / socket API and
```
workspaceGroups
```
config. See references/groups.md.

编辑用户cmux配置的单一入口，配置文件位于

~/.config/cmux/cmux.json

（JSONC格式）。应用会监听该文件；保存后立即生效，无需重启。旧版

~/.config/cmux/settings.json

仅作为

cmux.json

中缺失键的 fallback 读取。

包含三个配置领域，每个领域都有参考文档：

设置 —— 属于
```
app
```
、
```
terminal
```
、
```
notifications
```
、
```
sidebar
```
、
```
sidebarAppearance
```
、
```
workspaceColors
```
、
```
automation
```
、
```
browser
```
、
```
shortcuts
```
下的类型化偏好设置。可查看下方辅助脚本及references/all-keys.md / references/shortcut-actions.md。
自定义 —— 结构化配置：
```
actions
```
、
```
ui.surfaceTabBar.buttons
```
、
```
ui.newWorkspace
```
（加号按钮点击+上下文菜单）、
```
commands
```
、
```
rightSidebar
```
、
```
vault
```
。详见references/customize.md。
工作区组 —— 通过
```
cmux workspace group
```
CLI/套接字API和
```
workspaceGroups
```
配置实现可折叠的锚点所属侧边栏区域。详见references/groups.md。

Helper script

辅助脚本

Use the bundled helper for every settings/customize read and write. It strips JSONC comments, writes atomically, and validates keys against the schema. From the installed skill directory:

bash

./scripts/cmux-settings <subcommand>

For brevity below, assume it is on

$PATH

cmux-settings

(e.g.

export PATH="$HOME/.claude/skills/cmux-config/scripts:$PATH"

Command	What it does
`cmux-settings path`	Print the config path.
`cmux-settings dump [--no-comments]`	Print the raw file (or parsed JSON).
`cmux-settings get <a.b.c>`	Print value at dotted JSON path.
`cmux-settings set <a.b.c> <value>`	Set value ( `<value>` parsed as JSON; bare words stored as strings).
`cmux-settings unset <a.b.c>`	Delete key, reverting to the in-app default.
`cmux-settings list-supported`	List every settings JSON path the app recognizes.
`cmux-settings validate`	Parse the file and flag unknown settings keys.
`cmux-settings open`	Open `cmux.json` in `$EDITOR` / VS Code / Cursor / TextEdit.

--file <path>

overrides the target file (use for the legacy

settings.json

Schema:

https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json

使用内置辅助脚本进行所有设置/自定义的读写操作。它会去除JSONC注释、原子化写入，并根据 schema 验证键。从已安装的skill目录执行：

bash

./scripts/cmux-settings <subcommand>

为简化后续操作，假设该脚本已添加到

$PATH

中，命名为

cmux-settings

（例如：

export PATH="$HOME/.claude/skills/cmux-config/scripts:$PATH"

）。

命令	功能
`cmux-settings path`	打印配置文件路径。
`cmux-settings dump [--no-comments]`	打印原始文件内容（或解析后的JSON）。
`cmux-settings get <a.b.c>`	打印指定点式JSON路径的值。
`cmux-settings set <a.b.c> <value>`	设置指定路径的值（ `<value>` 会被解析为JSON；纯文本将存储为字符串）。
`cmux-settings unset <a.b.c>`	删除指定键，恢复为应用默认值。
`cmux-settings list-supported`	列出应用识别的所有设置JSON路径。
`cmux-settings validate`	解析文件并标记未知的设置键。
`cmux-settings open`	在 `$EDITOR` /VS Code/Cursor/TextEdit中打开 `cmux.json` 。

--file <path>

参数可覆盖目标文件（用于旧版

settings.json

）。

Schema地址：

https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json

。

Workflow

工作流程

If the user named a setting in plain English, look it up first:
```
cmux-settings list-supported | rg -i '<keywords>'
```
.
Make the smallest edit (settings/customize via the helper; groups via the
```
cmux workspace group
```
CLI in references/groups.md).
Verify by surface:
- Typed settings: read back (
```
cmux-settings get <path>
```
  ) and
```
cmux-settings validate
```
  .
- Customization (
```
actions
```
  ,
```
ui.*
```
  ,
```
commands
```
  ,
```
vault
```
  ,
```
rightSidebar
```
  ): read back the exact key (
```
cmux-settings get <path>
```
  ) and confirm the file still parses (
```
cmux-settings dump --no-comments
```
  ). Do NOT rely on
```
validate
```
  here: it skips structural sections, so a typo like
```
ui.surfaceTabbar.buttons
```
  passes validation yet cmux ignores it. Check the key against references/customize.md.
- Groups:
```
cmux workspace group list
```
  (the settings validator does not recognize
```
workspaceGroups
```
  ).
Tell the user it auto-reloaded on save. No app restart. Revert with
```
cmux-settings unset <key>
```
.

如果用户用普通英文提及某个设置，先通过以下命令查找：
```
cmux-settings list-supported | rg -i '<keywords>'
```
。
进行最小化修改（设置/自定义通过辅助脚本；工作区组通过references/groups.md中的
```
cmux workspace group
```
CLI）。
通过以下方式验证：
- 类型化设置：读取返回值（
```
cmux-settings get <path>
```
  ）并执行
```
cmux-settings validate
```
  。
- 自定义配置（
```
actions
```
  、
```
ui.*
```
  、
```
commands
```
  、
```
vault
```
  、
```
rightSidebar
```
  ）：读取精确键值（
```
cmux-settings get <path>
```
  ）并确认文件仍可解析（
```
cmux-settings dump --no-comments
```
  ）。请勿依赖
  validate
  命令：它会跳过结构化区域，因此像
```
ui.surfaceTabbar.buttons
```
  这样的拼写错误会通过验证，但cmux会忽略该配置。请对照references/customize.md检查键名。
- 工作区组：执行
```
cmux workspace group list
```
  （设置验证器不识别
```
workspaceGroups
```
  ）。
告知用户保存后配置会自动重载，无需重启应用。可通过
```
cmux-settings unset <key>
```
恢复配置。

Rules

规则

Only edit
```
cmux.json
```
. Never edit
```
settings.json
```
unless asked; it is legacy.
Never tell the user to restart cmux to apply a change; the watcher reloads on save.
Do not blindly overwrite top-level structural sections (
```
actions
```
,
```
ui
```
,
```
commands
```
,
```
vault
```
,
```
rightSidebar
```
); they hold hand-tuned non-settings config.
Color values are
```
#RRGGBB
```
; opacities are
```
0..1
```
.
Shortcut action ids must match the schema enum; look them up in references/shortcut-actions.md before binding.
Do not run a tagged app reload for config-only or skill-only changes.
For workspace groups prefer CLI/socket operations over editing session JSON, and preserve anchor semantics (see references/groups.md).

仅编辑
```
cmux.json
```
。除非用户要求，否则绝不编辑
```
settings.json
```
；它属于旧版配置。
绝不告知用户需要重启cmux才能应用更改；文件监听器会在保存时自动重载配置。
不要盲目覆盖顶层结构化区域（
```
actions
```
、
```
ui
```
、
```
commands
```
、
```
vault
```
、
```
rightSidebar
```
）；这些区域包含手动调整的非设置类配置。
颜色值格式为
```
#RRGGBB
```
；透明度值范围为
```
0..1
```
。
快捷键操作ID必须匹配schema枚举值；绑定前请在references/shortcut-actions.md中查找。
仅针对配置或skill的更改，无需触发标记的应用重载。
对于工作区组，优先使用CLI/套接字操作而非编辑会话JSON，并保留锚点语义（详见references/groups.md）。