cmux-settings

cmux-settings

cmux 从 ~/.config/cmux/cmux.json（JSONC）读取用户设置。应用会安装文件监视器；保存文件后会立即应用更改，无需重启。仅当 cmux.json 中不存在相应键时，才会将旧版 ~/.config/cmux/settings.json 作为备用文件读取。

架构：https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json。权威路径列表位于 repo/Sources/CmuxSettingsJSONPathSupport.swift。顶层部分包括 app、terminal、notifications、sidebar、sidebarAppearance、workspaceColors、automation、browser 和 shortcuts。非设置部分（actions、ui、commands、vault、rightSidebar）也与它们共存于同一文件中。

辅助脚本

每次读取或写入时都使用随附的辅助脚本。它会去除 JSONC 注释、以原子方式写入，并根据架构验证键。

# From the installed skill directory:
./scripts/cmux-settings <subcommand>

为简洁起见，本文其余部分假定脚本位于 $PATH 中，名称为 cmux-settings。若要在当前会话中实现这一点，请将该 skill 的 scripts/ 目录添加到 $PATH：

export PATH="$(dirname "$(realpath "$0")")/scripts:$PATH"   # from inside the skill
# or, after installing with skills.sh:
export PATH="$HOME/.claude/skills/cmux-settings/scripts:$PATH"

子命令：

命令	功能
cmux-settings path	打印配置路径。
cmux-settings dump	打印原始文件（保留注释）。
cmux-settings dump --no-comments	打印解析后的 JSON。
cmux-settings get <a.b.c>	打印点分隔 JSON 路径对应的值。
cmux-settings set <a.b.c> <value>	设置值。<value> 会按 JSON 解析（true、42、"text"、[…]、{…}）；不带引号的普通字符串会作为字符串存储。
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> 可指定目标文件（当用户将内容保存在旧版文件中时，可使用 --file ~/.config/cmux/settings.json）。

工作流

1. 确认更改。如果用户用自然语言提到了某项设置（例如“让侧边栏色调与终端背景一致”），请先查找该设置。

   cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar'
   

2. 设置值。JSON 字面量（true、false、数字、数组、对象）必须是有效 JSON。普通词语会作为字符串存储。

   cmux-settings set sidebarAppearance.matchTerminalBackground true
   cmux-settings set app.appearance dark
   cmux-settings set shortcuts.bindings.toggleSidebar cmd+b
   cmux-settings set shortcuts.bindings.newTab '["ctrl+b","c"]'
   cmux-settings set browser.hostsToOpenInEmbeddedBrowser '["localhost","*.internal.example"]'
   

3. 通过读取并验证来确认结果。

   cmux-settings get sidebarAppearance.matchTerminalBackground
   cmux-settings validate
   

4. 告知用户设置已自动重新加载，无需重启应用。如需恢复，请运行 cmux-settings unset <key>。

快速参考

• 外观：app.appearance = "system" | "light" | "dark"、app.appIcon、app.menuBarOnly、app.minimalMode。
• 侧边栏色调：sidebarAppearance.matchTerminalBackground、sidebarAppearance.tintColor、sidebarAppearance.tintOpacity（0..1）。
• 侧边栏详情：sidebar.hideAllDetails、sidebar.showBranchDirectory、sidebar.showPullRequests、sidebar.showPorts、sidebar.showLog。
• 通知：notifications.dockBadge、notifications.sound（枚举值包括 "none"、"custom_file"）、notifications.customSoundFilePath、notifications.hooks（数组）。
• 浏览器：browser.defaultSearchEngine、browser.theme、browser.openTerminalLinksInCmuxBrowser、browser.hostsToOpenInEmbeddedBrowser。
• 自动化：automation.socketControlMode（off | cmuxOnly | automation | password | allowAll）、automation.portBase、automation.portRange。
• 快捷键：shortcuts.bindings.<actionId> = "cmd+b"、["ctrl+b","c"]、null 或 ""（用于解除绑定）。请参阅 references/shortcut-actions.md。

如需查看完整的设置列表、默认值和说明，请运行 cmux-settings list-supported 或阅读 references/all-keys.md。

规则

• 只能编辑 cmux.json。除非用户明确要求，否则绝不要编辑 settings.json；它是旧版文件，仅当 cmux.json 中不存在相应键时才会读取。
• 应用更改时，绝不要让用户重启 cmux。文件监视器会在保存后重新加载。
• 批量编辑后务必验证：cmux-settings validate。未知键表示用户粘贴了应用不会读取的键。
• 不要盲目覆盖顶层部分（actions、ui、commands、vault、rightSidebar）。它们位于同一文件中，包含用户手动调整过的非设置配置。
• 快捷键动作 ID 必须与架构枚举相匹配。绑定前请查阅 references/shortcut-actions.md。
• 颜色值必须为 #RRGGBB。不透明度范围为 0..1。
• 对于用户用应用界面语言表述的设置（例如“设置 > 通知 > Dock 徽章”），请先转换为对应的 JSON 路径；repo/web/app/[locale]/docs/configuration/page.tsx 中的文档页面与架构一一对应。