# 配置

cmux 从 Ghostty 配置文件中读取配置，如果你之前使用 Ghostty，这些选项会很熟悉。

## 配置文件位置

cmux 按以下顺序查找配置：

1.  `~/.config/ghostty/config`
2.  `~/Library/Application Support/com.mitchellh.ghostty/config`

如果配置文件不存在，请创建：

```
mkdir -p ~/.config/ghostty
touch ~/.config/ghostty/config
```

## 配置示例

~/.config/ghostty/config

```
font-family = SF Mono
font-size = 13
sidebar-font-size = 14
surface-tab-bar-font-size = 11
theme = One Dark
scrollback-limit = 50000000
split-divider-color = #3e4451
working-directory = ~/code
```

## cmux.json

cmux keeps app-owned settings, shortcuts, actions, custom commands, and workspace layouts in `~/.config/cmux/cmux.json`. Terminal rendering still lives in Ghostty config. On launch, if the file is missing, cmux writes a commented template there.

Open cmux Settings, then use the `cmux.json` section to open the canonical file in your preferred text editor.

1.  `~/.config/cmux/cmux.json`
2.  `.cmux/cmux.json` in a project for project-scoped actions and workspace commands

**Precedence:** global `~/.config/cmux/cmux.json` settings override values saved in the Settings window. Legacy `~/.config/cmux/settings.json` and Application Support settings files are read only as fallback for missing settings keys. Project-local `.cmux/cmux.json` can override actions, commands, UI action wiring, and notification hooks, but not global app preferences.

**Reload:** edit the file, then use `Cmd+Shift+,` or `cmux reload-config` to re-read it without restarting the app.

**Migrations:** keep `schemaVersion` at `1` for now. Future cmux versions will use that field for upgrades. If cmux sees a newer schema version, it logs a warning and parses known keys only.

The file accepts JSON with comments and trailing commas. The canonical schema is published at [https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json](https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json) and the source lives at [https://github.com/manaflow-ai/cmux/blob/main/web/data/cmux.schema.json](https://github.com/manaflow-ai/cmux/blob/main/web/data/cmux.schema.json).

~/.config/cmux/cmux.json

```
{
  "$schema": "https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json",
  "schemaVersion": 1,

  // "app": {
  //   "appearance": "dark",
  //   "menuBarOnly": false,
  //   "newWorkspacePlacement": "afterCurrent",
  //   "windowTitleTemplate": "[cmux:{windowToken}] {activeWorkspace}",
  //   "paneResizeStepPixels": 20,
  //   "confirmQuit": "always",
  //   "openSupportedFilesInCmux": true,
  //   "workspaceInheritWorkingDirectory": true,
  //   "iMessageMode": true
  // },

  // "terminal": {
  //   "showScrollBar": false,
  //   "copyOnSelect": true,
  //   "autoResumeAgentSessions": true,
  //   "showTextBoxOnNewTerminals": false,
  //   "focusTextBoxOnNewTerminals": false,
  //   "agentHibernation": {
  //     "enabled": false,
  //     "idleSeconds": 5,
  //     "maxLiveTerminals": 12
  //   },
  //   "textBoxMaxLines": 10
  // },

  // "browser": {
  //   "defaultSearchEngine": "kagi",
  //   // For an unlisted provider, set "defaultSearchEngine": "custom" and fill these:
  //   "customSearchEngineName": "My Search",
  //   "customSearchEngineURLTemplate": "https://search.example.com/?q={query}",
  //   "openTerminalLinksInCmuxBrowser": true,
  //   "hostsToOpenInEmbeddedBrowser": ["localhost", "*.internal.example"]
  // },

  // "markdown": {
  //   // Default body font size (points) for newly opened markdown viewers.
  //   // Zoom a viewer live with Cmd-+ / Cmd-- / Cmd-0.
  //   "fontSize": 15,
  //   // Default body font family. Empty keeps the system markdown font stack.
  //   "fontFamily": "",
  //   // Default maximum reading column width, in CSS pixels.
  //   "maxWidth": 980
  // },

  // "fileEditor": {
  //   // Wrap long lines at the editor's right edge instead of scrolling horizontally.
  //   "wordWrap": false
  // },

  // "fileExplorer": {
  //   // 双击文件：preview（默认）、defaultEditor（macOS 默认应用）或 preferredEditor（app.preferredEditor 命令）。
  //   "doubleClickAction": "preview"
  // },

  // "automation": {
  //   "suppressSubagentNotifications": true
  // },

  // "workspaceColors": {
  //   "colors": {
  //     "Red": "#C0392B",
  //     "Blue": "#1565C0",
  //     "Neon Mint": "#00F5D4"
  //   }
  // },

  // "workspaceGroups": {
  //   "newWorkspacePlacement": "afterCurrent"
  // },

  // "agentChat": {
  //   "url": "http://127.0.0.1:7739",
  //   "startCommand": "cmux-chat"
  // },

  // "shortcuts": {
  //   "bindings": {
  //     "toggleSidebar": "cmd+b",
  //     "toggleFileExplorer": "cmd+opt+b",
  //     "toggleFileEditorWordWrap": "opt+z",
  //     "newTab": ["ctrl+b", "c"],
  //     "commandPalettePrevious": null
  //   }
  // },
}
```

## Schema reference

This reference covers every supported global settings key in `cmux.json`. The embedded browser, terminal, sidebar, notifications, automation, and cmux-owned keyboard shortcuts all live here. Actions and workspace commands are documented on the [custom commands page](https://cmux.com/zh-CN/docs/custom-commands).

### Metadata

`$schema`

Optional schema URL for editor completion and validation.

Type

`string`

Default

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

`schemaVersion`

Schema version for forward-compatible migrations. Newer versions are parsed on a best-effort basis.

Type

`integer`

Default

`1`

### `app`

General app preferences from Settings > App.

`app.language`

Preferred app language.

Type

`string`

Default

`"system"`

Allowed values

`system, en, ar, bs, zh-Hans, zh-Hant, da, de, es, fr, it, ja, ko, nb, pl, pt-BR, ru, th, tr`

`app.appearance`

App appearance mode.

Type

`string`

Default

`"system"`

Allowed values

`system, light, dark`

`app.accentColor`

Accent for cmux-drawn chrome: the selected workspace, attention ring and pane flash, agent status, pane swap, canvas focus, and scroll markers. "cmux" uses cmux blue; "system" follows the macOS accent color and updates when it changes; a "#RRGGBB" hex uses that color in light and dark mode. workspaceColors.selectionColor and notifications.paneFlashColor still override their parts. Native controls always use the macOS accent.

Type

`string | unknown`

Default

`"cmux"`

`app.appIcon`

Dock and app switcher icon style.

Type

`string`

Default

`"automatic"`

Allowed values

`automatic, light, dark`

`app.windowTitleTemplate`

可选的 NSWindow 标题模板。留空会保留 cmux 现有的默认标题行为，包括回退到当前目录。支持的占位符：{windowId}、{windowToken}、{activeWorkspace}、{activeDirectory}、{defaultTitle}、{appName}。

Type

`string`

Default

`""`

`app.devWindowDisplay`

仅在 DEBUG 构建中打开新窗口时使用的显示器名称。空值使用系统默认设置。

Type

`string`

Default

`""`

`app.menuBarOnly`

Hide the Dock icon and app switcher entry while keeping cmux available from the menu bar.

Type

`boolean`

Default

`false`

`app.newWorkspacePlacement`

Where new workspaces are inserted in the sidebar.

Type

`string`

Default

`"afterCurrent"`

Allowed values

`top, afterCurrent, end`

`app.goToWorkspaceOrder`

Order used by Go to Workspace (Cmd-P): sidebar order, or most recently focused workspaces.

Type

`string`

Default

`"sidebar"`

Allowed values

`sidebar, recent`

`app.forkConversationDefaultDestination`

标签页上下文菜单中主要 Fork Conversation 操作的默认目标。子菜单仍会显示所有目标。

Type

`string`

Default

`"right"`

Allowed values

`right, left, top, bottom, newTab, newWorkspace`

`app.workspaceInheritWorkingDirectory`

When true, new workspaces inherit the current workspace working directory. When false, new workspaces use Ghostty's working-directory setting instead.

Type

`boolean`

Default

`true`

`app.minimalMode`

Hide the workspace title bar and move controls into the sidebar.

Type

`boolean`

Default

`false`

`app.keepWorkspaceOpenWhenClosingLastSurface`

When true, closing the last surface keeps the workspace open.

Type

`boolean`

Default

`false`

`app.focusPaneOnFirstClick`

When cmux is inactive, the first click can activate and focus the clicked pane.

Type

`boolean`

Default

`false`

`app.paneResizeStepPixels`

Pixels moved per keypress when using pane-resize shortcuts. Accepts 1–200; defaults to 20. Changes apply immediately.

Type

`integer`

Default

`20`

`app.focusHistoryIncludesPanesAndTabs`

When true, Back and Forward include focus changes between panes and tabs. When false, they navigate between workspaces only.

Type

`boolean`

Default

`false`

`app.equalizeSplitsOnCreate`

When true, creating a split resizes the panes in that split's row or column to equal sizes. When false, a new split halves the pane it was created from.

Type

`boolean`

Default

`false`

`app.preferredEditor`

Custom editor command used when Cmd-click file previews are disabled or a file is unsupported. Leave empty to use the default.

Type

`string`

Default

`""`

`app.defaultWorkspacePath`

Folder the Open Folder panel starts in, for example ~/code. Supports a leading ~. Leave empty to start in the active workspace's directory.

Type

`string`

Default

`""`

`app.openSupportedFilesInCmux`

When enabled, Cmd-clicking readable local files opens supported previews in cmux, including text, code, PDFs, images, audio, video, and Quick Look files. Preview headers include an Open With menu based on the user's default and compatible macOS apps for that file.

Type

`boolean`

Default

`true`

`app.openMarkdownInCmuxViewer`

When enabled, Cmd-clicking .md/.markdown/.mkd/.mdx files opens the rendered cmux markdown viewer panel (with live reload) instead of the generic file preview.

Type

`boolean`

Default

`true`

`app.globalFontMagnification`

按百分比缩放 cmux 自行绘制的所有内容：终端文本、标签页标题、侧边栏、设置、浮层和窗口边框。浏览器 surface 中的网页保持自身的大小。

Type

`integer`

Default

`100`

`app.reorderOnNotification`

Automatic workspace reordering. true or "notifications" moves workspaces with new notifications toward the top. "agentActivity" also moves them when a prompt is sent or an agent finishes a turn, needs input, or fails, at most once per burst and never while the pointer is over the sidebar. false or "off" keeps the order stable.

Type

`boolean | string`

Default

`true`

`app.iMessageMode`

Move a workspace to the top and show the submitted message when sending an agent prompt.

Type

`boolean`

Default

`false`

`app.sendAnonymousTelemetry`

Allow anonymous telemetry.

Type

`boolean`

Default

`true`

`app.confirmQuit`

控制 cmux 在退出前何时请求确认。无论此设置如何，DEV 构建都会立即退出。旧的 app.warnBeforeQuit 仍作为布尔回退值接受。

Type

`string`

Default

`"always"`

Allowed values

`always, dirty-only, never`

`app.warnBeforeQuit`

用于退出确认的旧布尔回退值。新配置请使用 app.confirmQuit。

Type

`boolean`

Default

`true`

`app.warnBeforeClosingTab`

Show a confirmation before closing a tab.

Type

`boolean`

Default

`true`

`app.warnBeforeClosingAgentSession`

Show a confirmation before closing an agent session while it is mid-turn.

Type

`boolean`

Default

`true`

`app.warnBeforeClosingTabXButton`

使用标签关闭按钮关闭标签前显示确认。

Type

`boolean`

Default

`false`

`app.warnBeforeClosingWorkspace`

Show a confirmation before closing a workspace with a running process, or several workspaces at once. Pinned workspaces still ask when this is off.

Type

`boolean`

Default

`true`

`app.warnBeforeClosingWindow`

Show a confirmation before closing a window with a running process, or all of a window's workspaces at once.

Type

`boolean`

Default

`true`

`app.hideTabCloseButton`

在窗格标签栏中隐藏标签关闭按钮。

Type

`boolean`

Default

`false`

`app.tabBarVisibility`

决定窗格何时绘制其标签栏。"always" 即使窗格只有一个标签也会绘制；"multiple-tabs" 在窗格只有一个标签时隐藏，开启第二个标签后绘制。极简模式（app.minimalMode）始终绘制，因为在该模式下顶部窗格的标签栏同时充当窗口标题栏。

Type

`string`

Default

`"always"`

Allowed values

`always, multiple-tabs`

`app.renameSelectsExistingName`

Select the current name when opening rename flows.

Type

`boolean`

Default

`true`

`app.commandPaletteSearchesAllSurfaces`

Search every surface in the command palette switcher instead of only the active workspace.

Type

`boolean`

Default

`false`

### `terminal`

Terminal presentation settings from Settings > Terminal.

`terminal.adaptiveDefaultTheme`

为 true（默认）时，除非配置了 Ghostty 主题或终端颜色，否则 cmux 会提供随外观变化的默认配色。字体和其他设置会保留。为 false 时，Ghostty 使用固定的内置配色。显式主题和颜色始终优先，包括 theme = light:X,dark:Y。

Type

`boolean`

Default

`true`

`terminal.showScrollBar`

Show the right-edge terminal scroll bar when scrollback is available. cmux automatically suppresses it for alternate-screen style TUI surfaces.

Type

`boolean`

Default

`true`

`terminal.scrollSpeed`

调整每次鼠标滚轮或触控板滚动事件让终端移动的距离。大于 1 的值会加快滚动，小于 1 的值会减慢滚动。

Type

`number`

Default

`1`

`terminal.sessionContentMaxWidth`

终端和内置代理聊天内容的可选最大宽度，单位为点。设为 false 可使用整个窗格宽度。

Type

`boolean | number`

Default

`false`

`terminal.sessionContentAlignment`

启用 sessionContentMaxWidth 时，终端和内置代理聊天内容的水平位置。

Type

`string`

Default

`"center"`

Allowed values

`left, center, right`

`terminal.copyOnSelect`

为 true 时，在确认选择后将所选终端文本复制到系统剪贴板。为 false 时，cmux 不会输出 Ghostty copy-on-select 覆盖项；选择剪贴板行为由 Ghostty 配置和默认值控制。

Type

`boolean`

Default

`false`

`terminal.showCopyConfirmation`

Briefly show "Copied to clipboard" at the bottom of a terminal after selecting text copies it. Applies whether copyOnSelect or Ghostty's copy-on-select turned copying on. Copies made with a keyboard shortcut or by a program (OSC 52) never show it.

Type

`boolean`

Default

`false`

`terminal.reflowHardWrapOnCopy`

When true, copying terminal text also joins a line that exactly fills the terminal width onto the next line, undoing hard wraps a program inserted at the grid edge. Soft-wrapped rows are always joined.

Type

`boolean`

Default

`false`

`terminal.confirmUnsafePaste`

When true, a paste that Ghostty's clipboard-paste-protection flags as unsafe (for example, text with a line break going to a program that has not enabled bracketed paste) waits for confirmation in a sheet attached to the terminal's window. When false, cmux pastes it without asking. OSC 52 clipboard reads are not affected.

Type

`boolean`

Default

`false`

`terminal.textEditingGestures`

Replay macOS text-editing gestures as line-editor keys at the shell prompt: Command and Option arrow keys move by line and word, and Command and Option Delete kill by line and word. While a full-screen application (vim, less, htop, tmux) has the terminal on the alternate screen, it gets the keys as if gestures were off, unless textEditingGesturesInFullScreenApps is on. Ghostty's own bindings still apply there, so Command+Left sends Ctrl+A and Option+Left sends Esc b.

Type

`boolean`

Default

`false`

`terminal.textEditingCommandMovesByWord`

With textEditingGestures on, switch to a browser-style layout: Command arrow and Delete keys move and delete by word, like Option, and Control+Left/Right move to the start and end of the line. Every other Control chord, including Ctrl+W and Ctrl+C, still reaches the terminal. macOS reserves Control+Left/Right for switching Spaces by default; turn those off in System Settings > Keyboard > Keyboard Shortcuts > Mission Control for Control+arrows to reach cmux.

Type

`boolean`

Default

`false`

`terminal.textEditingGesturesInFullScreenApps`

Keep textEditingGestures active while a full-screen application has the terminal on the alternate screen. tmux, screen, and zellij keep the outer terminal on the alternate screen even at their shell prompt, so turn this on to use gestures inside a multiplexer. Applications that bind the gesture chords themselves then receive the translated keys.

Type

`boolean`

Default

`false`

`terminal.showPasswordInputIndicator`

Show a lock badge in the terminal corner while the foreground program has turned echo off for a password prompt (sudo, ssh, passwd, gpg). cmux draws the badge itself and never changes terminal text. Only prompts on the local terminal are detected: an ssh password prompt counts, but sudo run inside an ssh session does not. Changes apply to an open prompt at once.

Type

`boolean`

Default

`true`

`terminal.showPasswordInputDots`

When the password input badge is shown, also draw one dot per typed character. cmux keeps only a count, never the typed characters. Backspace removes a dot; Enter or echo turning back on clears them. Pasted text is not counted.

Type

`boolean`

Default

`false`

`terminal.showJumpToBottomButton`

Removed. cmux no longer shows a Jump to Bottom button in terminal panes, and ignores this key. It stays in the schema so existing configs still validate.

Type

`boolean`

Default

`none`

`terminal.predictiveLocalEcho`

Draw typed characters immediately in a terminal whose shell runs on another machine (cmux ssh, Cloud, remote tmux) when the link is slow, underlined until the remote echo confirms them, and withdraw them if the remote disagrees. Local terminals, password prompts and full-screen apps are excluded.

Type

`boolean`

Default

`true`

`terminal.autoResumeAgentSessions`

Automatically run agent resume commands for restored terminal sessions when cmux reopens after quit. Set false to restore panes while keeping Claude Code, Codex, OpenCode, and other saved agent sessions idle until you resume them manually.

Type

`boolean`

Default

`true`

`terminal.showTextBoxOnNewTerminals`

默认在新建的工作区、终端标签页和终端分屏中显示TextBox 输入。

Type

`boolean`

Default

`false`

`terminal.focusTextBoxOnNewTerminals`

默认在新建的工作区、终端标签页和终端分屏中聚焦TextBox 输入。聚焦也会显示 TextBox。

Type

`boolean`

Default

`false`

`terminal.agentHibernation`

Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical pressure from macOS or from the cmux app's own footprint, or cmux's total memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.

Type

`object`

Default

`none`

`terminal.rendererRealization`

Reclaim off-screen terminal GPU renderer memory. cmux releases the Metal renderer (IOSurface) of a terminal that has stayed off-screen and idle while keeping its process and terminal state alive, then rebuilds the renderer instantly when the tab is visited again. Non-destructive and on by default.

Type

`object`

Default

`none`

`terminal.titleUpdates`

Terminal title update throttling and diagnostics.

Type

`object`

Default

`none`

`terminal.runawayMemoryGuardrail`

Per-pane process-tree memory monitoring.

Type

`object`

Default

`none`

`terminal.textBoxMaxLines`

Maximum number of lines the rich terminal TextBox input can grow to before it scrolls.

Type

`integer`

Default

`10`

`terminal.textBoxDefaultSubmitAction`

Default TextBox submit action ID for new terminal sessions. Use text-entry for plain input or one of the configured action IDs.

Type

`string`

Default

`"text-entry"`

`terminal.textBoxSubmitActions`

Configurable TextBox submit actions shown on the submit button, Shift-Tab cycle, and right-click menu.

Type

`array<object>`

Default

```
[]
```

`terminal.resumeCommands`

Signed command-prefix approvals for restoring non-agent terminal surfaces. cmux writes this list when you approve a surface resume command.

Type

`array<object>`

Default

```
[]
```

`terminal.uploadCommands`

Host-scoped rules that replace the built-in scp for terminal file drops and pastes over SSH. When the ssh destination matches a rule, cmux runs that rule's command once per file instead of scp, and inserts the command's stdout at the cursor (verbatim, with control characters stripped); if the command prints nothing, cmux inserts the shell-escaped remote path it chose instead. Per-file outputs are space-joined. First matching enabled rule wins; no match runs the built-in scp unchanged. A non-zero exit, timeout, or cancel inserts nothing.

Type

`array<object>`

Default

```
[]
```

### `notifications`

Notification behavior from Settings > Notifications.

`notifications.dockBadge`

Show the unread count in the Dock tile.

Type

`boolean`

Default

`true`

`notifications.showInMenuBar`

Show the menu bar extra.

Type

`boolean`

Default

`true`

`notifications.unreadPaneRing`

Highlight panes with unread notifications.

Type

`boolean`

Default

`true`

`notifications.paneFlash`

Flash the focused pane when requested.

Type

`boolean`

Default

`true`

`notifications.paneFlashDoubleBlink`

Blink the pane flash twice instead of one short pulse.

Type

`boolean`

Default

`true`

`notifications.paneFlashOnTyping`

Flash the pane when terminal typing dismisses its notification.

Type

`boolean`

Default

`true`

`notifications.paneFlashThemeColor`

Use the terminal theme foreground for flashes when paneFlashColor is unset. Unread rings remain cmux blue.

Type

`boolean`

Default

`false`

`notifications.paneFlashColor`

Override the pane flash and unread notification ring color. Leave unset to use the accent from app.accentColor.

Type

`unknown`

Default

`null`

`notifications.soundWhenFocused`

即使发出通知的窗格已处于焦点状态，也播放通知声音。默认关闭，因此处于焦点的窗格只显示光环和闪烁。

Type

`boolean`

Default

`false`

`notifications.suppressOnlyFocusedSurface`

启用后，仅当通知横幅的 Surface 恰好是当前聚焦的 Surface 时，该横幅才会自动撤回。对于当前可见 workspace 中未聚焦的 Surface 所投递的横幅，在你聚焦该 Surface（或点击/关闭它）之前会一直显示，而不会在 workspace 变为可见时被撤回。关闭则保留旧的基于 workspace 可见性的撤回行为。

Type

`boolean`

Default

`false`

`notifications.suppressWhenAppFocused`

启用后，只要 cmux 是当前活跃的应用，cmux 就会对所有通知跳过桌面横幅，而不仅限于获得焦点的窗格。通知仍会显示在侧边栏中，声音和自定义命令也仍会运行，转发到手机的行为不变。关闭时，即使 cmux 获得焦点，其他 workspace 和窗格的横幅也会继续显示。

Type

`boolean`

Default

`false`

`notifications.agentPermissionPrompt`

Notify when an agent (e.g. Claude Code) is blocked waiting for your permission to run a tool. On by default, since this is the alert you must act on to unblock the agent.

Type

`boolean`

Default

`true`

`notifications.agentTurnComplete`

When to notify that an agent finished a turn. whenIdle (default) suppresses the notification while the agent still has a running background task or a pending scheduled wakeup, so you are pinged once work truly drains. always notifies on every turn end; never disables it.

Type

`string`

Default

`"whenIdle"`

Allowed values

`whenIdle, always, never`

`notifications.agentIdleReminder`

当代理空闲并等待你的输入时（回合结束后约 60 秒）发送通知。只要上一回合的后台工作仍在等待，就会抑制通知，避免正在运行的构建或监视器触发错误的等待提醒。

Type

`boolean`

Default

`true`

`notifications.sound`

Notification sound preset.

Type

`string`

Default

`"default"`

Allowed values

`default, Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink, custom_file, none`

`notifications.customSoundFilePath`

Local path to the custom notification sound file.

Type

`string`

Default

`""`

`notifications.soundOverrides`

按代理和提醒类型设置的稀疏通知声音覆盖。缺少的单元格使用 notifications.sound。

Type

`object`

Default

```
{}
```

`notifications.command`

Optional shell command to run alongside notification delivery.

Type

`string`

Default

`""`

`notifications.hooksMode`

Controls whether project-local notification hooks append to inherited hooks or replace them.

Type

`string`

Default

`"append"`

Allowed values

`append, replace`

`notifications.hooks`

Composable shell hooks that receive notification policy JSON on stdin and return updated policy JSON on stdout.

Type

`array<object>`

Default

```
[]
```

### `sidebar`

Sidebar content and metadata visibility from Settings > Sidebar.

`sidebar.fontSize`

Sidebar font size in points. The legacy Ghostty key sidebar-font-size remains a fallback alias.

Type

`number`

Default

`12.5`

`sidebar.hideAllDetails`

Hide all per-workspace detail rows.

Type

`boolean`

Default

`false`

`sidebar.wrapWorkspaceTitles`

Allow workspace titles in the sidebar to wrap to multiple lines instead of truncating after one line.

Type

`boolean`

Default

`false`

`sidebar.showWorkspaceDescription`

Show custom workspace descriptions in the sidebar.

Type

`boolean`

Default

`true`

`sidebar.workspaceDescriptionColor`

Override the workspace description text color in the sidebar.

Type

`unknown`

Default

`null`

`sidebar.beta`

Experimental sidebar features.

Type

`object`

Default

`none`

`sidebar.branchLayout`

Show git branch details stacked vertically or inline.

Type

`string`

Default

`"vertical"`

Allowed values

`vertical, inline`

`sidebar.branchVerticalLayout`

Show git branch details stacked vertically when true, or inline when false. This boolean form is the canonical setting; branchLayout remains supported as a legacy alias.

Type

`boolean`

Default

`true`

`sidebar.stackBranchDirectory`

Render the git branch and working directory on separate lines instead of sharing one line.

Type

`boolean`

Default

`false`

`sidebar.pathLastSegmentOnly`

Truncate sidebar paths from the start, showing as much of the trailing path as fits with a leading …/. When false, full paths are abbreviated with ~/.

Type

`boolean`

Default

`false`

`sidebar.showNotificationMessage`

Show the latest notification text in the sidebar.

Type

`boolean`

Default

`true`

`sidebar.notificationMessageLineLimit`

每个工作区标题下方显示的最新通知的最大行数。

Type

`integer`

Default

`12`

`sidebar.showBranchDirectory`

Show the workspace working directory.

Type

`boolean`

Default

`true`

`sidebar.showCloudDeviceIcons`

无论 Git 分支和目录详细信息如何，都在远程工作区标题旁显示 Cloud 电脑和设备图标。

Type

`boolean`

Default

`true`

`sidebar.showPullRequests`

Show pull request metadata in the sidebar.

Type

`boolean`

Default

`true`

`sidebar.watchGitStatus`

Watch repository files for sidebar branch and pull request metadata without polling git.

Type

`boolean`

Default

`true`

`sidebar.makePullRequestsClickable`

Allow sidebar pull request metadata to open links when clicked.

Type

`boolean`

Default

`true`

`sidebar.openPullRequestLinksInCmuxBrowser`

Open sidebar pull request links in the embedded cmux browser.

Type

`boolean`

Default

`true`

`sidebar.openPortLinksInCmuxBrowser`

Open sidebar port links in the embedded cmux browser.

Type

`boolean`

Default

`true`

`sidebar.showSSH`

Show SSH connection details.

Type

`boolean`

Default

`true`

`sidebar.showPorts`

Show listening ports.

Type

`boolean`

Default

`true`

`sidebar.showLog`

Show recent log snippets.

Type

`boolean`

Default

`true`

`sidebar.showProgress`

Show progress indicators.

Type

`boolean`

Default

`true`

`sidebar.showAgentUsage`

在 Claude Code 或 Codex 的状态条目后附加编码代理的用量：所用模型和已占用的上下文窗口，并在 Claude Code 上按 Anthropic 公布的标价给出 API 费用估算（主线程与子代理）。该费用仅为估算，并非你的订阅账单；批处理／优先级档位、合作伙伴定价、快速模式以及服务器工具费用均未计入。

Type

`boolean`

Default

`false`

`sidebar.showAgentActivity`

Show the loading spinner on workspaces with running coding agents or active loaders.

Type

`boolean`

Default

`true`

`sidebar.loadingSpinnerPosition`

Which side of the workspace row the loading spinner appears on: leading (left, sharing the unread-badge slot) or trailing (right).

Type

`string`

Default

`"leading"`

Allowed values

`leading, trailing`

`sidebar.notificationBadgePosition`

Which side of the workspace row the unread notification badge appears on: leading (left) or trailing (right).

Type

`string`

Default

`"leading"`

Allowed values

`leading, trailing`

`sidebar.showCustomMetadata`

Show custom metadata pills.

Type

`boolean`

Default

`true`

`sidebar.compactAgentStatus`

每个工作区只显示一行：标题前的单个彩色图标表示代理、未读和拉取请求状态，取代代理状态行（例如“运行中”或“需要输入”）、分支和目录行以及拉取请求行，这些详细信息移到图标的提示中。其他状态条目保留各自的行。

Type

`boolean`

Default

`false`

`sidebar.compactStatusIcons`

按状态替换 compactAgentStatus 字形的 SF Symbol 名称，例如 {"terminal": "apple.terminal", "needsInput": "hand.raised.fill"}。未设置的状态使用内置符号，无法显示的名称也会回退到内置符号。

Type

`object`

Default

```
{}
```

`sidebar.activeTabIndicatorStyle`

Active workspace indicator style in the sidebar.

Type

`string`

Default

`"leftRail"`

Allowed values

`leftRail, solidFill, rail, border, wash, lift, typography, washRail, blueWashColorRail`

`sidebar.selectionColor`

Override the selected workspace background color in the sidebar.

Type

`unknown`

Default

`null`

`sidebar.notificationBadgeColor`

Override the unread notification badge color in the sidebar.

Type

`unknown`

Default

`null`

`sidebar.rightMaxWidth`

右侧边栏的最大宽度（点）。省略时使用内置动态上限。

Type

`number`

Default

`none`

### `workspaceGroups`

Per-cwd customization for sidebar workspace groups. The anchor workspace's cwd is matched against the keys in \`byCwd\`; longest-match wins. Keys containing \`\*\` or \`?\` are matched as fnmatch globs (with \`~\` expanded); other keys are path prefixes.

`workspaceGroups.newWorkspacePlacement`

组内 Cmd-N、组标题中的 + 按钮以及已配置的组操作放置新 workspace 的全局默认位置：\`afterCurrent\`（在当前活动的组内 workspace 后面，没有时回退到 top）、\`top\`（第二个位置，紧跟锚点之后）或 \`end\`（最后一个成员之后）。

Type

`string`

Default

`"afterCurrent"`

Allowed values

`afterCurrent, top, end`

`workspaceGroups.byCwd`

Map of cwd patterns to group customization. Empty when omitted.

Type

`object`

Default

`none`

### `workspaceColors`

Workspace tab and badge colors from Settings > Workspace Colors.

`workspaceColors.indicatorStyle`

Active workspace indicator style. Legacy aliases are accepted and normalized.

Type

`string`

Default

`"leftRail"`

Allowed values

`leftRail, solidFill, rail, border, wash, lift, typography, washRail, blueWashColorRail`

`workspaceColors.selectionColor`

Override the selected workspace background color.

Type

`unknown`

Default

`null`

`workspaceColors.subtleSelection`

Show the selected workspace as a faint accent tint with a thin edge instead of a solid fill. A custom selectionColor still uses a solid fill.

Type

`boolean`

Default

`false`

`workspaceColors.brightenInDarkMode`

Lighten workspace colors in dark mode so they stay readable on a dark sidebar. false shows colors exactly as chosen. Applies to the solidFill indicator; leftRail always lightens its rail.

Type

`boolean`

Default

`true`

`workspaceColors.notificationBadgeColor`

Override the unread notification badge color.

Type

`unknown`

Default

`null`

`workspaceColors.colors`

Full named workspace color palette. Include built-in entries you want to keep, remove keys to remove colors, and add more named entries to extend the picker.

Type

`object`

Default

```
{
  "Red": "#C0392B",
  "Crimson": "#922B21",
  "Orange": "#A04000",
  "Amber": "#7D6608",
  "Olive": "#4A5C18",
  "Green": "#196F3D",
  "Teal": "#006B6B",
  "Aqua": "#0E6B8C",
  "Blue": "#1565C0",
  "Navy": "#1A5276",
  "Indigo": "#283593",
  "Purple": "#6A1B9A",
  "Magenta": "#AD1457",
  "Rose": "#880E4F",
  "Brown": "#7B3F00",
  "Charcoal": "#3E4B5E"
}
```

`workspaceColors.paletteOverrides`

Legacy workspace color overrides for built-in palette names. Prefer workspaceColors.colors for new configs.

Type

`object`

Default

```
{}
```

`workspaceColors.customColors`

Legacy list of custom workspace colors. Prefer workspaceColors.colors for new configs.

Type

`array<unknown>`

Default

```
[]
```

`workspaceColors.colors` is the full palette. Keep the built-in keys you want, delete keys to remove colors from the picker, and add more named color entries to extend it. Older `paletteOverrides` and `customColors` files still parse during upgrades, but new files should use `colors`.

```
{
  "workspaceColors": {
    "colors": {
      "Red": "#C0392B",
      "Blue": "#1565C0",
      "Neon Mint": "#00F5D4"
    }
  }
}
```

### `sidebarAppearance`

Sidebar tint settings from Settings > Sidebar Appearance.

`sidebarAppearance.matchTerminalBackground`

Use the terminal background instead of the sidebar tint.

Type

`boolean`

Default

`true`

`sidebarAppearance.tintColor`

Base sidebar tint color used when light/dark overrides are not set.

Type

`unknown`

Default

`"#000000"`

`sidebarAppearance.lightModeTintColor`

Sidebar tint override for light appearance.

Type

`unknown`

Default

`null`

`sidebarAppearance.darkModeTintColor`

Sidebar tint override for dark appearance.

Type

`unknown`

Default

`null`

`sidebarAppearance.tintOpacity`

Sidebar tint opacity from 0 to 1. Note: this only controls the sidebar tint, not terminal/window transparency. For terminal background transparency or blur, set \`background-opacity\` and \`background-blur\` in \`~/.config/ghostty/config\` and run \`cmux reload-config\`.

Type

`number`

Default

`0.18`

### `automation`

Socket control and automation settings from Settings > Automation.

`automation.socketControlMode`

Socket control mode. Legacy aliases are accepted and normalized.

Type

`string`

Default

`"cmuxOnly"`

Allowed values

`off, cmuxOnly, automation, password, allowAll, openAccess, fullOpenAccess, notifications, full`

`automation.socketPassword`

Password for password-mode socket access. Use null or an empty string to clear it.

Type

`string | null`

Default

`""`

`automation.claudeCodeIntegration`

Enable cmux integration hooks for Claude Code.

Type

`boolean`

Default

`true`

`automation.codexIntegration`

Enable cmux integration hooks for Codex. When disabled, cmux no longer wraps the codex command but still tracks live Codex sessions it can observe.

Type

`boolean`

Default

`true`

`automation.canonicalAgentScratch`

Use a cmux-owned scratch directory for native agent panels, organized per session.

Type

`boolean`

Default

`false`

`automation.piIntegration`

Enable cmux integration hooks for Pi.

Type

`boolean`

Default

`true`

`automation.claudeBinaryPath`

Custom path to the claude binary.

Type

`string`

Default

`""`

`automation.workspaceAutoNaming`

可选的 AI 自动命名：根据代理对话内容自动命名工作区和标签页。启用后，cmux 会使用各受支持代理自己的二进制文件将会话总结为简短标题；手动重命名始终优先。

Type

`boolean`

Default

`false`

`automation.autoNamingAgent`

为每个会话生成自动名称的代理。"auto"（默认）使用各会话自己的代理来命名；任意代理标识（claude、codex、grok、opencode、pi、omp 等）会覆盖所有会话的命名，包括其他代理的会话。无法驱动或未安装的代理会回退到会话自身的代理，因此命名永不中断。

Type

`string`

Default

`"auto"`

`automation.ripgrepBinaryPath`

Custom path to the ripgrep (rg) binary used by project search.

Type

`string`

Default

`""`

`automation.suppressSubagentNotifications`

隐藏嵌套 Codex 或 Claude 子代理的可见完成通知和状态变更，同时将其事件保留在 Feed 遥测中。

Type

`boolean`

Default

`true`

`automation.agentAutoResume`

当 cmux 启动的代理因可重试的上游错误（模型容量已满、过载或连接中断）结束回合时，按退避策略向其发送 \`continue\`。等待人工输入的回合永远不会被恢复。

Type

`boolean`

Default

`true`

`automation.ampIntegration`

开启或关闭 cmux 的 Amp 钩子。关闭后，捆绑的插件仍保持安装，但处于闲置状态。

Type

`boolean`

Default

`true`

`automation.cursorIntegration`

Enable cmux integration hooks for Cursor.

Type

`boolean`

Default

`true`

`automation.geminiIntegration`

Enable cmux integration hooks for Gemini.

Type

`boolean`

Default

`true`

`automation.kiroIntegration`

Enable cmux integration hooks for Kiro CLI.

Type

`boolean`

Default

`true`

`automation.kiroNotificationLevel`

Controls how many Kiro tool events appear in Feed.

Type

`string`

Default

`"standard"`

Allowed values

`minimal, standard, verbose`

`automation.portBase`

Starting value for workspace CMUX\_PORT assignments.

Type

`integer`

Default

`9100`

`automation.portRange`

Number of ports reserved per workspace.

Type

`integer`

Default

`10`

### `ui`

UI action wiring, including surface tab bar buttons and plus-button behavior. The plus-button context menu shows ui.newWorkspace.contextMenu (or the default items) followed by actions that opt in via newWorkspaceMenu.

`ui.newWorkspace`

New Workspace button behavior and context-menu wiring.

Type

`object`

Default

`none`

### `agentChat`

Agent Chat GUI server settings. The built-in New agent chat action opens this URL in a browser workspace, probes /healthz first, and can run a configured start command when the server is down.

`agentChat.url`

Base URL for the machine-local Agent Chat GUI server. cmux probes <url>/healthz before opening the workspace.

Type

`string`

Default

`"http://127.0.0.1:7739"`

`agentChat.startCommand`

Optional shell command to start the Agent Chat server when <url>/healthz is unreachable. cmux runs it detached with the user's SHELL, polls healthz for a short bounded window, then opens the workspace either way.

Type

`string`

Default

`none`

`agentChat.keys`

Keyboard behavior overrides for the Agent Chat web UI.

Type

`object`

Default

`none`

`agentChat.fonts`

Font overrides for the Agent Chat web UI. Omitted values fall back to Ghostty and built-in defaults.

Type

`object`

Default

`none`

### `browser`

Embedded browser settings from Settings > Browser.

`browser.defaultSearchEngine`

浏览器地址栏输入不是 URL 时使用的默认搜索引擎。对于任意提供商，请使用 custom 和 customSearchEngineURLTemplate。

Type

`string`

Default

`"google"`

Allowed values

`google, duckduckgo, bing, kagi, startpage, brave, perplexity, exa, yahoo, ecosia, qwant, mojeek, wikipedia, github, baidu, yandex, custom`

`browser.customSearchEngineName`

defaultSearchEngine 为 custom 时使用的显示名称。

Type

`string`

Default

`""`

`browser.customSearchEngineURLTemplate`

defaultSearchEngine 为 custom 时使用的搜索 URL。使用查询占位符或 %s 表示已编码的查询。如果没有占位符，cmux 会向 URL 添加 q=。

Type

`string`

Default

`"https://www.google.com/search?q={query}"`

`browser.showSearchSuggestions`

Show omnibar search suggestions.

Type

`boolean`

Default

`true`

`browser.theme`

Embedded browser theme.

Type

`string`

Default

`"system"`

Allowed values

`system, light, dark`

`browser.defaultZoomLevel`

Default page zoom factor applied to newly opened browser pages (1 = 100%). Zoom In, Zoom Out, and Actual Size still adjust each page.

Type

`number`

Default

`1`

`browser.discardHiddenWebViews`

Allow hidden browser tabs to release page memory. Scroll position, supported form input, and history are restored when recoverable.

Type

`boolean`

Default

`true`

`browser.hiddenWebViewDiscardMode`

How cmux picks hidden browser tabs to free. budget frees the tabs hidden longest once hidden tabs use more than hiddenWebViewMemoryBudgetMB; timer frees every tab hidden longer than hiddenWebViewDiscardDelaySeconds.

Type

`string`

Default

`"budget"`

Allowed values

`budget, timer`

`browser.hiddenWebViewMemoryBudgetMB`

Megabytes of memory hidden browser tabs may use before cmux frees the tabs hidden longest. Applies when hiddenWebViewDiscardMode is budget.

Type

`integer`

Default

`2048`

`browser.hiddenWebViewDiscardDelaySeconds`

Seconds a browser tab must stay hidden before cmux may free its page memory. In timer mode, every tab hidden this long is freed.

Type

`number`

Default

`300`

`browser.autoRestoreUnloadedPages`

Restore a browser page unloaded to save memory, or whose web process ended while hidden, as soon as its tab is shown. When false, the tab shows the page's last snapshot until you click Restore.

Type

`boolean`

Default

`true`

`browser.askWhereToSaveDownloads`

Show a save panel for browser downloads instead of saving directly to Downloads.

Type

`boolean`

Default

`false`

`browser.showLinkHoverURL`

指针停留在链接上或链接获得键盘焦点时，在浏览器面板左下角显示链接的目标地址。

Type

`boolean`

Default

`true`

`browser.openTerminalLinksInCmuxBrowser`

Open clicked terminal links in the embedded browser.

Type

`boolean`

Default

`true`

`browser.interceptTerminalOpenCommandInCmuxBrowser`

Intercept terminal open http(s) commands and route them through the embedded browser.

Type

`boolean`

Default

`true`

`browser.hostsToOpenInEmbeddedBrowser`

Allowlist of hosts that should stay inside the embedded browser.

Type

`array<string>`

Default

```
[]
```

`browser.urlsToAlwaysOpenExternally`

Rules that always open matching URLs in the system browser.

Type

`array<string>`

Default

```
[]
```

`browser.insecureHttpHostsAllowedInEmbeddedBrowser`

HTTP hosts allowed in the embedded browser without a warning prompt.

Type

`array<string>`

Default

```
[
  "localhost",
  "*.localhost",
  "127.0.0.1",
  "::1",
  "0.0.0.0",
  "*.localtest.me"
]
```

`browser.urlAllowlist`

限制内嵌浏览器导航的主机或 URL 模式。设置界面会建议本地开发来源；保存列表后会启用可选限制。删除条目即可阻止这些来源；没有托管策略时，将用户值留空可禁用限制。

Type

`array<string>`

Default

```
[
  "localhost",
  "*.localhost",
  "127.0.0.1",
  "::1",
  "0.0.0.0",
  "*.localtest.me"
]
```

`browser.showImportHintOnBlankTabs`

Show the browser import hint on blank tabs.

Type

`boolean`

Default

`true`

`browser.reactGrabVersion`

Pinned react-grab version for the browser toolbar helper.

Type

`string`

Default

`"0.1.29"`

### `markdown`

Built-in markdown viewer settings.

`markdown.fontSize`

Default body font size, in points, for newly opened markdown viewers. Zoom a viewer live with Cmd-+ / Cmd-- / Cmd-0.

Type

`integer`

Default

`15`

`markdown.fontFamily`

Default body font family for newly opened markdown viewers. Leave empty for the system markdown font stack.

Type

`string`

Default

`""`

`markdown.maxWidth`

Default maximum reading column width, in CSS pixels, for newly opened markdown viewers.

Type

`integer`

Default

`980`

### `fileEditor`

Built-in file editor settings.

`fileEditor.wordWrap`

对超出编辑器宽度的行进行软换行，因此无需横向滚动。

Type

`boolean`

Default

`false`

`fileEditor.syntaxHighlighting`

为在内置文件编辑器中打开的代码应用按语言区分的着色。

Type

`boolean`

Default

`true`

`fileEditor.lineNumbers`

在内置文件编辑器中，于正文旁的一列显示每一行的行号。

Type

`boolean`

Default

`true`

`fileEditor.indentGuides`

在内置文件编辑器中，用一条细竖线标出每一级缩进。

Type

`boolean`

Default

`true`

`fileEditor.currentLineHighlight`

在没有选中内容时，为光标所在的行着色。

Type

`boolean`

Default

`true`

`fileEditor.tabWidth`

一个制表位占用的列数。缩进参考线使用相同的间距。

Type

`integer`

Default

`4`

### `fileExplorer`

右侧边栏文件浏览器（文件树）设置。

`fileExplorer.doubleClickAction`

设置在文件浏览器中双击文件（或在搜索结果上按 Return）时执行的操作。\`preview\` 会打开 cmux 内置文件预览（默认和历史行为）。\`defaultEditor\` 会使用该文件类型的 macOS 默认应用打开。\`preferredEditor\` 会使用 \`app.preferredEditor\` 命令打开；未设置时回退到默认应用。仅适用于文件；目录始终展开/折叠，非本地（远程）文件浏览器始终打开 cmux 预览。

Type

`string`

Default

`"preview"`

Allowed values

`preview, defaultEditor, preferredEditor`

### `shortcuts`

Keyboard shortcut settings from Settings > Keyboard Shortcuts.

`shortcuts.showModifierHoldHints`

在按住 Cmd 或 Control 时显示快捷键提示标签。

Type

`boolean`

Default

`true`

`shortcuts.when`

每个操作可选的上下文谓词（VS Code 风格的 \`when\` 子句），按 cmux 操作 id 索引。每个值都是基于上下文键的布尔表达式，可用 !、&&、|| 和括号组合。布尔键：sidebarFocus、browserFocus、markdownFocus、filePreviewTextEditorFocus、simulatorFocus、terminalFocus、commandPaletteVisible、terminalFindVisible、terminalAlternateScreen、workspaceCanvasLayout。类型化键支持比较：字符串 sidebarMode（files、find、sessions、feed 或 dock）以及整数 paneCount 和 workspaceCount。比较运算符为 ==、!=、=~（正则表达式）、<、<=、>、>= 和 \`in \[a, b\]\`；未知或不存在的键按 false 处理。也接受布尔字面量 true 和 false；\`key == false\` 等同于 \`!key\`。只有当子句成立时，该操作的快捷键才会触发，也只会在这种情况下与其他快捷键冲突。示例：{ "selectWorkspaceByNumber": "!sidebarFocus" } 让 Ctrl+1–9 在右侧边栏未聚焦时选择工作区；{ "selectSurfaceByNumber": "sidebarMode == 'find' && paneCount > 1" } 在工作区有多个窗格时将绑定限定在查找侧边栏。

Type

`object`

Default

```
{}
```

### `shortcuts.bindings`

Use a string for a single shortcut, a two-item array for a chord, or `null` to unbind a shortcut in `shortcuts.bindings`. Unbind aliases also include empty string (`""`), `none`, `clear`, `unbound`, and `disabled`. Example chord: `["ctrl+b", "c"]`. Numbered actions use `1` as the stored default and still match digits `1` through `9`.

The defaults below are the same cmux-owned actions listed on the [keyboard shortcuts page](https://cmux.com/zh-CN/docs/keyboard-shortcuts).

#### App

`openSettings`

Settings

Default file value

`cmd+,`

`openTeamPicker`

打开团队选择器

Default file value

`opt+shift+cmd+t`

`reloadConfiguration`

Reload configuration

Default file value

`cmd+shift+,`

`showHideAllWindows`

Show/hide all cmux windowssystem-wide hotkey

Default file value

`ctrl+opt+cmd+.`

`globalSearch`

Global searchwhen cmux is active

Default file value

`opt+cmd+f`

`commandPalette`

Command palette

Default file value

`cmd+shift+p`

`agentInbox`

显示代理收件箱

Default file value

`cmd+shift+i`

`commandPaletteNext`

Command palette next resultwhen the command palette is open

Default file value

`ctrl+n`

`commandPalettePrevious`

Command palette previous resultwhen the command palette is open

Default file value

`ctrl+p`

`newWindow`

New window

Default file value

`cmd+shift+n`

`closeWindow`

Close window

Default file value

`ctrl+cmd+w`

`toggleFullScreen`

Toggle full screen

Default file value

`ctrl+cmd+f`

`sendFeedback`

Send feedbackunbound by default

Default file value

`reopenPreviousSession`

Reopen previous session

Default file value

`cmd+shift+o`

`quit`

Quit cmux

Default file value

`cmd+q`

#### 工作区

`toggleSidebar`

Toggle left sidebar

Default file value

`cmd+b`

`toggleFileExplorer`

Toggle right sidebar

Default file value

`cmd+opt+b`

`newTab`

新建本地工作区

Default file value

`cmd+n`

`newLocalWorkspace`

新建本地工作区在远程 tmux 镜像工作区处于活动状态时打开本地工作区；此时“新建工作区”会改为在该工作区的主机上启动会话

Default file value

`ctrl+opt+cmd+n`

`newBrowserWorkspace`

New browser workspacelike New Workspace, but the first surface is a browser pane with the address bar focused

Default file value

`opt+cmd+n`

`newCloudWorkspace`

新建云工作区使用最近选中的 Cloud 工作区所属机器；如果没有，则使用右侧边栏中第一台机器；如果没有可用机器，则打开 New Cloud Machine

Default file value

`cmd+y`

`newCloudMachine`

新建云机器

Default file value

`shift+cmd+y`

`saveLayoutTemplate`

Save current workspace layout as a template

Default file value

`ctrl+cmd+s`

`openFolder`

Open folder

Default file value

`cmd+o`

`goToWorkspace`

Go to workspaceworkspace switcher

Default file value

`cmd+p`

`nextSidebarTab`

Next workspace

Default file value

`ctrl+cmd+]`

`prevSidebarTab`

Previous workspace

Default file value

`ctrl+cmd+[`

`nextSidebarTabInGroup`

Next workspace in groupunbound by default; skips the group anchor and uses window-wide cycling when ungrouped

Default file value

`prevSidebarTabInGroup`

Previous workspace in groupunbound by default; skips the group anchor and uses window-wide cycling when ungrouped

Default file value

`moveWorkspaceUp`

Move workspace up

Default file value

`ctrl+opt+cmd+[`

`moveWorkspaceDown`

Move workspace down

Default file value

`ctrl+opt+cmd+]`

`focusHistoryBack`

Focus backFocus Back/Forward use Cmd+\[ and Cmd+\] outside browser panes; browser Back/Forward use the same defaults inside browser panes. Unbind Focus Back/Forward to let terminal shortcuts handle those keys.

Default file value

`cmd+[`

`focusHistoryForward`

Focus forwardFocus Back/Forward use Cmd+\[ and Cmd+\] outside browser panes; browser Back/Forward use the same defaults inside browser panes. Unbind Focus Back/Forward to let terminal shortcuts handle those keys.

Default file value

`cmd+]`

`focusHistoryLast`

Focus lastunbound by default; toggles between the current position and the one focus last left, so pressing it twice returns where you started

Default file value

`selectWorkspaceByNumber`

Select workspace 1…9

Default file value

`cmd+1`

`renameWorkspace`

Rename workspace

Default file value

`cmd+shift+r`

`editWorkspaceDescription`

Edit workspace description

Default file value

`opt+cmd+e`

`markWorkspaceDone`

Mark workspace as done

Default file value

`cmd+;`

`cycleWorkspaceStatus`

Cycle workspace status one lane forward

Default file value

`cmd+shift+;`

`toggleChecklistItemComplete`

Toggle the highlighted checklist itemApplies in the focused todo pane or checklist popover.

Default file value

`cmd+enter`

`newWorkspaceGroup`

New empty workspace group

Default file value

`ctrl+cmd+g`

`groupSelectedWorkspaces`

Group selected workspaces

Default file value

`cmd+shift+g`

`toggleFocusedWorkspaceGroupCollapsed`

Collapse or expand focused workspace group

Default file value

`ctrl+cmd+.`

`focusSidebar`

Focus the workspace sidebar↑/↓ select workspaces; Return or Esc returns to the terminal

Default file value

`ctrl+cmd+e`

`showWindowHints`

Click by hint: label the window's controlsType a label to click it, Shift+label to right-click; Esc cancels. Preview feature, off by default: turn on Click by Hint in Settings > Beta Features or from the command palette

Default file value

`cmd+j`

`focusRightSidebar`

Toggle right-sidebar focus

Default file value

`cmd+shift+e`

`navigateRightSidebarRows`

Navigate focused sidebar rowsIn Files, H/L collapse and expand folders. Search starts with /.

Default file value

`j / k`

`fileExplorerOpenSelection`

打开所选文件或切换文件夹聚焦的文件资源管理器

Default file value

`enter`

`fileExplorerOpenSelectionFinderAlias`

打开所选文件或切换文件夹聚焦的文件资源管理器的 Finder 风格别名

Default file value

`cmd+down`

`closeWorkspace`

Close workspace

Default file value

`cmd+shift+w`

`reopenClosedWorkspace`

Reopen closed workspaceunbound by default

Default file value

#### Surface

`newSurface`

New surface

Default file value

`cmd+t`

`nextSurface`

Next surface

Default file value

`cmd+shift+]`

`prevSurface`

Previous surface

Default file value

`cmd+shift+[`

`moveSurfaceLeft`

Reorder surface left

Default file value

`opt+cmd+shift+[`

`moveSurfaceRight`

Reorder surface right

Default file value

`opt+cmd+shift+]`

`moveSurfaceToPreviousPane`

Move surface to previous pane

Default file value

`ctrl+cmd+shift+[`

`moveSurfaceToNextPane`

Move surface to next pane

Default file value

`ctrl+cmd+shift+]`

`moveSurfaceToPaneLeft`

Move surface to pane on left

Default file value

`opt+cmd+shift+left`

`moveSurfaceToPaneRight`

Move surface to pane on right

Default file value

`opt+cmd+shift+right`

`moveSurfaceToPaneUp`

Move surface to pane above

Default file value

`opt+cmd+shift+up`

`moveSurfaceToPaneDown`

Move surface to pane below

Default file value

`opt+cmd+shift+down`

`selectSurfaceByNumber`

Select surface 1…9

Default file value

`ctrl+1`

`renameTab`

Rename tab

Default file value

`cmd+r`

`closeTab`

Close tab

Default file value

`cmd+w`

`closeOtherTabsInPane`

Close other tabs in pane

Default file value

`opt+cmd+t`

`reopenClosedBrowserPanel`

Reopen last closed

Default file value

`cmd+shift+t`

`toggleTerminalCopyMode`

Toggle terminal copy mode

Default file value

`cmd+shift+m`

`clearScreenKeepScrollback`

Clear screen (keep scrollback)

Default file value

`cmd+shift+k`

`simulatorHome`

Simulator: Homefocused Simulator

Default file value

`cmd+shift+h`

`simulatorRotateLeft`

Simulator: rotate leftfocused Simulator

Default file value

`cmd+left`

`simulatorRotateRight`

Simulator: rotate rightfocused Simulator

Default file value

`cmd+right`

`simulatorToggleAppearance`

Simulator: toggle appearancefocused Simulator

Default file value

`cmd+shift+a`

`simulatorToggleSoftwareKeyboard`

Simulator: toggle software keyboardfocused Simulator

Default file value

`cmd+k`

`focusTextBoxInput`

Switch focus between terminal and TextBox input

Default file value

`cmd+shift+a`

`cycleTextBoxSubmitAction`

Cycle TextBox submit action

Default file value

`shift+tab`

`attachTextBoxFile`

Attach file to TextBox input

Default file value

`opt+cmd+shift+a`

`sendCtrlFToTerminal`

Send Ctrl-F to terminalunbound by default; forwards Ctrl-F to the focused terminal (Claude Code: invoke twice to force-stop hung background agents)

Default file value

`sizeTerminalToMyWindow`

Size shared terminal to my windowwhen a terminal is shared with phones or other clients, makes this Mac's window set its grid

Default file value

`ctrl+opt+cmd+=`

`pasteLastScreenshot`

粘贴最新的截图默认未绑定；将 macOS 截图文件夹（未更改时为桌面）中最新截图的路径插入焦点所在的终端，远程工作区会先上传文件

Default file value

`saveFilePreview`

Save file previewfocused text preview

Default file value

`cmd+s`

`toggleFileEditorWordWrap`

切换文件编辑器自动换行焦点所在的文件编辑器

Default file value

`opt+z`

#### 分屏面板

`focusLeft`

Focus pane left

Default file value

`opt+cmd+left`

`focusRight`

Focus pane right

Default file value

`opt+cmd+right`

`focusUp`

Focus pane up

Default file value

`opt+cmd+up`

`focusDown`

Focus pane down

Default file value

`opt+cmd+down`

`focusPreviousPane`

Focus previous pane (cycle)unbound by default; a Ghostty goto\_split:previous keybind also cycles panes while Focus Back does not claim the same keys

Default file value

`focusNextPane`

Focus next pane (cycle)unbound by default; a Ghostty goto\_split:next keybind also cycles panes while Focus Forward does not claim the same keys

Default file value

`focusPaneByNumber`

Focus pane 1…9

Default file value

`ctrl+cmd+1`

`splitRight`

Split right

Default file value

`cmd+d`

`splitDown`

Split down

Default file value

`cmd+shift+d`

`newPaneAutoLayout`

New pane (auto layout)retiles all panes like Zellij and cmux-tui Alt-n: the right column fills to four panes before a new column opens

Default file value

`ctrl+cmd+n`

`splitBrowserRight`

Split browser right

Default file value

`opt+cmd+d`

`splitBrowserDown`

Split browser down

Default file value

`opt+cmd+shift+d`

`toggleSplitZoom`

Toggle pane zoom

Default file value

`cmd+shift+enter`

`increaseWorkspaceTerminalFontSize`

Increase font size for every terminal in the selected workspace

Default file value

`ctrl+cmd+=`

`decreaseWorkspaceTerminalFontSize`

Decrease font size for every terminal in the selected workspace

Default file value

`ctrl+cmd+-`

`resetWorkspaceTerminalFontSize`

Reset font size for every terminal in the selected workspace

Default file value

`ctrl+cmd+0`

`equalizeSplits`

Equalize split sizes

Default file value

`ctrl+cmd+shift+=`

`resize-pane-left`

Resize pane left

Default file value

`ctrl+shift+h`

`resize-pane-right`

Resize pane right

Default file value

`ctrl+shift+l`

`resize-pane-up`

Resize pane up

Default file value

`ctrl+shift+k`

`resize-pane-down`

Resize pane down

Default file value

`ctrl+shift+j`

#### 画布

`toggleCanvasLayout`

Toggle canvas layout

Default file value

`ctrl+cmd+c`

`canvasRevealFocusedPane`

Reveal focused pane

Default file value

`ctrl+cmd+r`

`canvasOverview`

Toggle overview zoom

Default file value

`ctrl+cmd+o`

`canvasZoomIn`

Zoom in

Default file value

`opt+cmd+=`

`canvasZoomOut`

Zoom out

Default file value

`opt+cmd+-`

`canvasZoomReset`

Actual size

Default file value

`cmd+0`

`canvasTidy`

Tidy panes into a grid

Default file value

`ctrl+cmd+t`

#### 浏览器

`openBrowser`

Open browser

Default file value

`cmd+shift+l`

`focusBrowserAddressBar`

Focus address bar

Default file value

`cmd+l`

`browserBack`

Back

Default file value

`cmd+[`

`browserForward`

Forward

Default file value

`cmd+]`

`browserReload`

Reload pagefocused browser

Default file value

`cmd+r`

`browserHardReload`

强制刷新页面聚焦的浏览器

Default file value

`cmd+shift+r`

`browserZoomIn`

Zoom in

Default file value

`cmd+=`

`browserZoomOut`

Zoom out

Default file value

`cmd+-`

`browserZoomReset`

Actual size

Default file value

`cmd+0`

`markdownZoomIn`

Markdown viewer: zoom infocused markdown viewer

Default file value

`cmd+=`

`markdownZoomOut`

Markdown viewer: zoom outfocused markdown viewer

Default file value

`cmd+-`

`markdownZoomReset`

Markdown viewer: actual sizefocused markdown viewer

Default file value

`cmd+0`

`toggleBrowserDeveloperTools`

Toggle browser developer tools

Default file value

`opt+cmd+i`

`showBrowserJavaScriptConsole`

Show browser JavaScript console

Default file value

`opt+cmd+c`

`toggleBrowserFocusMode`

Enter browser focus modeGives the focused web page first claim on shortcuts. Press Esc twice to exit.

Default file value

`opt+cmd+enter`

`toggleBrowserDesignMode`

Toggle browser design modeSelect and visually edit elements in the focused browser

Default file value

`ctrl+opt+cmd+d`

`toggleReactGrab`

Toggle React Grabfocused browser, or the only browser pane when a terminal is focused

Default file value

`cmd+shift+g`

#### 差异查看器

`openDiffViewer`

Open diff viewer

Default file value

`ctrl+cmd+shift+d`

`diffViewerScrollDown`

Scroll viewer down one smooth stepfocused diff or Markdown viewer

Default file value

`j`

`diffViewerScrollUp`

Scroll viewer up one smooth stepfocused diff or Markdown viewer

Default file value

`k`

`diffViewerScrollHalfPageDown`

Scroll viewer down half a pagefocused diff or Markdown viewer

Default file value

`ctrl+d`

`diffViewerScrollHalfPageUp`

Scroll viewer up half a pagefocused diff or Markdown viewer

Default file value

`ctrl+u`

`diffViewerScrollDownEmacs`

Scroll viewer down one smooth step (Emacs)focused diff or Markdown viewer

Default file value

`ctrl+n`

`diffViewerScrollUpEmacs`

Scroll viewer up one smooth step (Emacs)focused diff or Markdown viewer

Default file value

`ctrl+p`

`diffViewerScrollToBottom`

Scroll diff to bottomfocused diff viewer

Default file value

`shift+g`

`diffViewerScrollToTop`

Scroll diff to topfocused diff viewer

Default file value

`["g", "g"]`

`diffViewerOpenFileSearch`

Open diff file searchfocused diff viewer

Default file value

`/`

`diffViewerNextFile`

Jump to next diff filefocused diff viewer

Default file value

`["]", "f"]`

`diffViewerPreviousFile`

Jump to previous diff filefocused diff viewer

Default file value

`["[", "f"]]`

`diffViewerNextHunk`

Jump to next hunkfocused diff viewer

Default file value

`"n"`

`diffViewerPreviousHunk`

Jump to previous hunkfocused diff viewer

Default file value

`"p"`

`diffViewerToggleViewed`

切换当前文件的已查看状态聚焦的差异查看器

Default file value

`"v"`

#### 查找

`find`

Find

Default file value

`cmd+f`

`findInDirectory`

Find in directory

Default file value

`cmd+shift+f`

`findNext`

Find next

Default file value

`cmd+g`

`findPrevious`

Find previous

Default file value

`opt+cmd+g`

`hideFind`

Hide find bar

Default file value

`opt+cmd+shift+f`

`useSelectionForFind`

Use selection for find

Default file value

`cmd+e`

#### 通知

`showNotifications`

Show notifications

Default file value

`cmd+i`

`jumpToUnread`

Jump to latest unread

Default file value

`cmd+shift+u`

`jumpToLastPrompt`

跳转到你上次向代理发送提示的界面

Default file value

`cmd+shift+b`

`toggleUnread`

Toggle current item unread state

Default file value

`opt+cmd+u`

`markOldestUnreadAndJumpNext`

Mark current item as oldest unread and jump to the next latest unread

Default file value

`ctrl+cmd+u`

`markAllNotificationsRead`

将所有通知标记为已读默认未绑定

Default file value

`clearAllNotifications`

清除所有通知默认未绑定

Default file value

`triggerFlash`

Flash focused panel

Default file value

`cmd+shift+h`

### `shortcuts.when`

每个操作可选的上下文谓词（VS Code 风格的 when 子句），按 cmux 操作 id 索引。只有当其子句成立时，绑定才会触发，也只会在这种情况下与同一按键上的其他绑定冲突。省略子句即保留操作的内置上下文。子句可用的词汇：

-   `sidebarFocus`, `browserFocus`, `markdownFocus`, `filePreviewTextEditorFocus`, `simulatorFocus`, `terminalFocus`, `commandPaletteVisible`, `terminalFindVisible`, `terminalAlternateScreen`, `workspaceCanvasLayout` — 布尔键。未知或不存在的键按 false 处理；也接受字面量 true 和 false。
-   `sidebarMode` (`files`, `find`, `sessions`, `feed`, `dock`), `paneCount`, `workspaceCount` — 用于比较的类型化键：右侧边栏的当前模式（字符串），以及窗格和工作区数量（整数）。
-   `!`, `&&`, `||`, `(…)`, `==`, `!=`, `=~`, `<`, `<=`, `>`, `>=`, `in [a, b]` — 布尔运算符、类型化比较、正则匹配和列表成员判断。比较的结合优先级高于 && 和 ||。

例如，下面的配置让 Ctrl+1–9 在右侧边栏未聚焦时选择工作区（把 Ctrl+1–5 留给侧边栏模式切换器），并在工作区有多个窗格时将表面选择限定在查找侧边栏：

```
"shortcuts": {
  "bindings": { "selectWorkspaceByNumber": "ctrl+1" },
  "when": {
    "selectWorkspaceByNumber": "!sidebarFocus",
    "selectSurfaceByNumber": "sidebarMode == 'find' && paneCount > 1"
  }
}
```

Canonical: https://cmux.com/zh-CN/docs/configuration

Documentation index: https://cmux.com/llms.txt