cmuxcmux
/docs

#設定

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 and the source lives at 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}",
  //   "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 預設 App）或 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",
  //     "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.

#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.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.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.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
true
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.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.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 擁有的終端機、分頁標題、側邊欄、設定、覆蓋層和應用程式 chrome。不包含已算繪的瀏覽器頁面內容。

Type
integer
Default
100
app.reorderOnNotification

Move workspaces with new notifications toward the top.

Type
boolean
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.warnBeforeClosingTabXButton

使用分頁關閉按鈕關閉分頁前顯示確認。

Type
boolean
Default
false
app.hideTabCloseButton

在窗格分頁列中隱藏分頁關閉按鈕。

Type
boolean
Default
false
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.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

套用於終端機滾輪與觸控板捲動量的倍率。數值越大捲動越快，數值越小捲動越慢。

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.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, during critical memory pressure cmux may hibernate a bounded batch of safe idle background agents 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.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.suppressOnlyFocusedSurface

啟用後，只有當通知橫幅的 Surface 正好是目前聚焦的 Surface 時，該橫幅才會自動撤回。對於目前可見 workspace 中未聚焦的 Surface 所投遞的橫幅，在你聚焦該 Surface（或點擊／關閉它）之前會持續顯示，而不會在 workspace 變為可見時被撤回。關閉則保留舊有的基於 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

Notify when an agent has been idle waiting for your input (about 60s after a turn ends). Suppressed while background work from the last turn is still pending, so a running build or watcher does not trigger a false waiting alert.

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.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.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.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.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.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.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.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.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
false
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.03

#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.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.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 會將 q= 加到 URL。

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.discardHiddenWebViews

Allow hidden browser tabs to release page memory and restore when shown again.

Type
boolean
Default
true
browser.hiddenWebViewDiscardDelaySeconds

Seconds a browser tab must stay hidden before cmux frees its page memory.

Type
number
Default
300
browser.askWhereToSaveDownloads

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

Type
boolean
Default
false
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.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 plain-text file editor settings.

fileEditor.wordWrap

Wrap long lines at the editor's right edge instead of scrolling horizontally.

Type
boolean
Default
false

#fileExplorer

右側邊欄檔案瀏覽器（檔案樹）設定。

fileExplorer.doubleClickAction

設定在檔案瀏覽器中按兩下檔案（或在搜尋結果上按 Return）時要執行的動作。`preview` 會開啟 cmux 內建檔案預覽（預設與既有行為）。`defaultEditor` 會使用該檔案類型的 macOS 預設 App 開啟。`preferredEditor` 會使用 `app.preferredEditor` 命令開啟；未設定時會退回預設 App。僅適用於檔案；目錄一律展開/收合，非本機（遠端）檔案瀏覽器一律開啟 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、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.

App

openSettings

Settings

Default file value
cmd+,
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
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

New workspace

Default file value
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
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+[
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+]
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+.
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
saveFilePreview

Save file previewfocused text preview

Default file value
cmd+s

分割窗格

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
splitRight

Split right

Default file value
cmd+d
splitDown

Split down

Default file value
cmd+shift+d
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+=

畫布

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"]]

搜尋

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
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
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, 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"
  }
}