cmux-config

cmux-config

用于编辑用户 cmux 配置 ~/.config/cmux/cmux.json（JSONC）的统一入口。应用会监视该文件；保存后会立即应用更改，无需重启。仅当 cmux.json 中缺少相应键时，才会将旧版 ~/.config/cmux/settings.json 作为回退读取。

三个区域，各有一份参考文档：

• 设置 — 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 / socket API 和 workspaceGroups 配置创建的可折叠侧边栏分区，由锚点拥有。请参阅 references/groups.md。

辅助脚本

读取和写入设置/自定义配置时，均使用附带的辅助工具。它会剥除 JSONC 注释、以原子方式写入，并根据架构验证键。从已安装的技能目录运行：

./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）。

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

工作流

1. 如果用户用自然语言提到了某项设置，先查找： cmux-settings list-supported | rg -i '<keywords>'。
2. 尽量只做最小改动（设置/自定义配置通过辅助工具修改；工作区组通过 references/groups.md 中的 cmux workspace group CLI 修改）。
3. 按配置类别进行验证：
   • 类型化设置： 读回确认（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）。
4. 告知用户保存后已自动重新加载，无需重启应用。使用 cmux-settings unset <key> 撤销更改。

规则

• 仅编辑 cmux.json。除非用户要求，否则绝不编辑 settings.json；它是旧版配置。
• 绝不要告诉用户重启 cmux 来应用更改；文件保存后，监视器会自动重新加载。
• 不要盲目覆盖顶层结构部分（actions、ui、 commands、vault、rightSidebar）；其中包含经过精细调整的非设置配置。
• 颜色值采用 #RRGGBB 格式；不透明度范围为 0..1。
• 快捷键操作 ID 必须与架构枚举一致；绑定前请查阅 references/shortcut-actions.md。
• 仅更改配置或技能时，不要执行带标签的应用重新加载。
• 对于工作区分组，优先使用 CLI/套接字操作，而不是编辑会话 JSON，并 保留锚点语义（请参阅 references/groups.md）。