Back to Details

cmux-settings

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cmux-settings

cmux设置

cmux reads user settings from 
~/.config/cmux/cmux.json
(JSONC). The app installs a file watcher; saving the file applies changes immediately, no restart needed. Legacy 
~/.config/cmux/settings.json
is read only as a fallback for keys not present in 
cmux.json
.
Schema: 
https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json
. The authoritative path list lives in 
Sources/CmuxSettingsJSONPathSupport.swift
in the cmux checkout, and the installed skill includes a generated copy in 
references/all-keys.md
. Top-level sections are 
app
, 
terminal
, 
notifications
, 
sidebar
, 
sidebarAppearance
, 
workspaceColors
, 
automation
, 
browser
, and 
shortcuts
. Non-settings sections (
actions
, 
ui
, 
commands
, 
vault
, 
rightSidebar
) coexist in the same file.
cmux 从
~/.config/cmux/cmux.json
（JSONC格式）读取用户设置。应用程序内置了文件监视器，保存文件后更改会立即生效，无需重启。旧版的
~/.config/cmux/settings.json
仅会作为
cmux.json
中未包含配置项的 fallback 被读取。
Schema地址：
https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json
。权威的配置路径列表存放在cmux代码库的
Sources/CmuxSettingsJSONPathSupport.swift
文件中，已安装的skill在
references/all-keys.md
中包含一份生成的副本。顶层配置分区包括
app
、
terminal
、
notifications
、
sidebar
、
sidebarAppearance
、
workspaceColors
、
automation
、
browser
和
shortcuts
。非设置类分区（
actions
、
ui
、
commands
、
vault
、
rightSidebar
）也存放在同一文件中。

Helper script

辅助脚本

Use the bundled helper for every read/write. It strips JSONC comments, writes atomically, and validates keys against the schema.
bash
undefined
请使用内置的辅助脚本进行所有读写操作。它会去除JSONC注释、以原子方式写入，并根据schema验证配置项。
bash
undefined

From a cmux checkout

从cmux代码库中执行

skills/cmux-settings/scripts/cmux-settings <subcommand>
skills/cmux-settings/scripts/cmux-settings <subcommand>

From an installed Codex skill

从已安装的Codex skill中执行

~/.codex/skills/cmux-settings/scripts/cmux-settings <subcommand>

For brevity in the rest of this doc, assume the script is on `$PATH` as `cmux-settings`. To make it so for a session from a checkout: `export PATH="$PWD/skills/cmux-settings/scripts:$PATH"`.

Subcommands:

| Command | What it does |
|---|---|
| `cmux-settings path` | Print the config path. |
| `cmux-settings dump` | Print the raw file (preserves comments). |
| `cmux-settings dump --no-comments` | Print the parsed JSON. |
| `cmux-settings get <a.b.c>` | Print value at dotted JSON path. |
| `cmux-settings set <a.b.c> <value>` | Set value. `<value>` is parsed as JSON (`true`, `42`, `"text"`, `[…]`, `{…}`); plain strings without quotes are 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 any unknown settings keys. |
| `cmux-settings open` | Open `cmux.json` in `$EDITOR`, VS Code, Cursor, or TextEdit. |

`--file <path>` overrides the target file (useful for `--file ~/.config/cmux/settings.json` when the user keeps things in the legacy file).
~/.codex/skills/cmux-settings/scripts/cmux-settings <subcommand>

为了简化本文档后续内容，假设脚本已添加到`$PATH`并可通过`cmux-settings`调用。若要在当前会话中从代码库添加路径：`export PATH="$PWD/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`）。

Workflow

操作流程

  1. Confirm the change. If the user named a setting in plain English (e.g. "make the sidebar tint match the terminal background"), look it up first.
    bash
    cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar'
  2. Set the value. JSON literals (
    true
    , 
    false
    , numbers, arrays, objects) must be valid JSON. Plain words are stored as strings.
    bash
    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. Verify by reading back and validating.
    bash
    cmux-settings get sidebarAppearance.matchTerminalBackground
cmux-settings validate
  4. Tell the user it auto-reloaded. No app restart. If they want to revert, run 
    cmux-settings unset <key>
    .
  1. 确认要修改的设置。如果用户用自然语言描述设置（例如“让侧边栏色调匹配终端背景”），请先查询对应的配置路径。
    bash
    cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar'
  2. 设置对应值。JSON字面量（
    true
    、
    false
    、数字、数组、对象）必须符合JSON格式规范。纯文本会被存储为字符串。
    bash
    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. 通过读取值和验证操作确认设置生效。
    bash
    cmux-settings get sidebarAppearance.matchTerminalBackground
cmux-settings validate
  4. 告知用户设置已自动重载，无需重启应用。若要恢复默认值，执行
    cmux-settings unset <key>
    即可。

Quick reference

快速参考

  • Appearance: 
    app.appearance
    = 
    "system" | "light" | "dark"
    , 
    app.appIcon
    , 
    app.menuBarOnly
    , 
    app.minimalMode
    .
  • Sidebar tint: 
    sidebarAppearance.matchTerminalBackground
    , 
    sidebarAppearance.tintColor
    , 
    sidebarAppearance.tintOpacity
    (0..1).
  • Sidebar details: 
    sidebar.hideAllDetails
    , 
    sidebar.showBranchDirectory
    , 
    sidebar.showPullRequests
    , 
    sidebar.showPorts
    , 
    sidebar.showLog
    .
  • Notifications: 
    notifications.dockBadge
    , 
    notifications.sound
    (enum incl. 
    "none"
    , 
    "custom_file"
    ), 
    notifications.customSoundFilePath
    , 
    notifications.hooks
    (array).
  • Browser: 
    browser.defaultSearchEngine
    , 
    browser.theme
    , 
    browser.openTerminalLinksInCmuxBrowser
    , 
    browser.hostsToOpenInEmbeddedBrowser
    .
  • Automation: 
    automation.socketControlMode
    (
    off | cmuxOnly | automation | password | allowAll
    ), 
    automation.portBase
    , 
    automation.portRange
    .
  • Shortcuts: 
    shortcuts.bindings.<actionId>
    = 
    "cmd+b"
    , 
    ["ctrl+b","c"]
    , 
    null
    , or 
    ""
    to unbind. See 
    references/shortcut-actions.md
    .
For the full list of settings, defaults, and descriptions, run 
cmux-settings list-supported
or read references/all-keys.md.
  • 外观设置：
    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。

Rules

注意规则

  • Only edit 
    cmux.json
    . Never edit 
    settings.json
    unless the user explicitly asks; it is legacy and only read when the key is absent from 
    cmux.json
    .
  • Never tell the user to restart cmux to apply a change. The file watcher reloads on save.
  • Always validate after a bulk edit: 
    cmux-settings validate
    . Unknown keys mean the user pasted a key the app does not consume.
  • Do not blindly overwrite top-level sections (
    actions
    , 
    ui
    , 
    commands
    , 
    vault
    , 
    rightSidebar
    ). They live in the same file and contain non-settings config the user has hand-tuned.
  • Shortcut action ids must match the schema enum. Look them up in references/shortcut-actions.md before binding.
  • Color values must be 
    #RRGGBB
    . Opacities are 
    0..1
    .
  • For settings the user expressed in app-level language (e.g. "Settings > Notifications > Dock badge"), translate to the matching JSON path first; the docs page at 
    web/app/[locale]/docs/configuration/page.tsx
    mirrors the schema 1:1.
  • 仅编辑
    cmux.json
    。除非用户明确要求，否则不要编辑
    settings.json
    ；该文件为旧版，仅在
    cmux.json
    中无对应配置项时才会被读取。
  • 切勿告知用户需要重启cmux才能应用更改。文件监视器会在保存时自动重载设置。
  • 批量编辑后务必执行验证：
    cmux-settings validate
    。未知配置项意味着用户粘贴了应用不识别的键。
  • 不要盲目覆盖顶层非设置类分区（
    actions
    、
    ui
    、
    commands
    、
    vault
    、
    rightSidebar
    ）。这些分区与设置项共存于同一文件中，包含用户手动调整的非配置类内容。
  • 快捷键动作ID必须与schema枚举值匹配。绑定前请先在references/shortcut-actions.md中查询。
  • 颜色值必须为
    #RRGGBB
    格式。透明度取值范围为0..1。
  • 对于用户用应用层级语言描述的设置（例如“设置 > 通知 > Dock图标标记”），请先转换为对应的JSON路径；
    web/app/[locale]/docs/configuration/page.tsx
    中的文档与schema完全对应。