cmux-settings

Source excerpt starting at line 1.

1# All settings keys2 3Auto-generated from `web/data/cmux.schema.json`. For the rendered docs, see `https://cmux.com/docs/configuration`.4 5## app6 7General app preferences from Settings > App.8 9| Key | Type | Default | Description |10|---|---|---|---|11| `app.language` | `"system"` or `"en"` or `"ar"` or `"bs"` or `"zh-Hans"` or `"zh-Hant"` or `"da"` or `"de"` or `"es"` or `"fr"` or `"it"` or `"ja"` or `"ko"` or `"nb"` or `"pl"` or `"pt-BR"` or `"ru"` or `"th"` or `"tr"` | `"system"` | Preferred app language. |12| `app.appearance` | `"system"` or `"light"` or `"dark"` | `"system"` | App appearance mode. |13| `app.appIcon` | `"automatic"` or `"light"` or `"dark"` | `"automatic"` | Dock and app switcher icon style. |14| `app.menuBarOnly` | boolean | `false` | Hide the Dock icon and app switcher entry while keeping cmux available from the menu bar. |15| `app.newWorkspacePlacement` | `"top"` or `"afterCurrent"` or `"end"` | `"afterCurrent"` | Where new workspaces are inserted in the sidebar. |16| `app.workspaceInheritWorkingDirectory` | boolean | `true` | When true, new workspaces inherit the current workspace working directory. When false, new workspaces use Ghostty's working-directory setting instead. |17| `app.minimalMode` | boolean | `false` | Hide the workspace title bar and move controls into the sidebar. |18| `app.keepWorkspaceOpenWhenClosingLastSurface` | boolean | `false` | When true, closing the last surface keeps the workspace open. |19| `app.focusPaneOnFirstClick` | boolean | `true` | When cmux is inactive, the first click can activate and focus the clicked pane. |20| `app.preferredEditor` | string | `""` | Custom editor command used when Cmd-click file previews are disabled or a file is unsupported. Leave empty to use the default. |21| `app.openSupportedFilesInCmux` | boolean | `true` | 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. |22| `app.openMarkdownInCmuxViewer` | boolean | `true` | 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. |23| `app.reorderOnNotification` | boolean | `true` | Move workspaces with new notifications toward the top. |24| `app.iMessageMode` | boolean | `false` | Move a workspace to the top and show the submitted message when sending an agent prompt. |25| `app.sendAnonymousTelemetry` | boolean | `true` | Allow anonymous telemetry. |26| `app.warnBeforeQuit` | boolean | `true` | Show a confirmation before quitting cmux. |27| `app.warnBeforeClosingTab` | boolean | `true` | Show a confirmation before closing a tab. |28| `app.renameSelectsExistingName` | boolean | `true` | Select the current name when opening rename flows. |29| `app.commandPaletteSearchesAllSurfaces` | boolean | `false` | Search every surface in the command palette switcher instead of only the active workspace. |30 31## terminal32 33Terminal presentation settings from Settings > Terminal.34 35| Key | Type | Default | Description |36|---|---|---|---|37| `terminal.showScrollBar` | boolean | `true` | Show the right-edge terminal scroll bar when scrollback is available. cmux automatically suppresses it for alternate-screen style TUI surfaces. |38| `terminal.autoResumeAgentSessions` | boolean | `true` | 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. |39 40## notifications41 42Notification behavior from Settings > Notifications.43 44| Key | Type | Default | Description |45|---|---|---|---|46| `notifications.dockBadge` | boolean | `true` | Show the unread count in the Dock tile. |47| `notifications.showInMenuBar` | boolean | `true` | Show the menu bar extra. |48| `notifications.unreadPaneRing` | boolean | `true` | Highlight panes with unread notifications. |49| `notifications.paneFlash` | boolean | `true` | Flash the focused pane when requested. |50| `notifications.sound` | `"default"` or `"Basso"` or `"Blow"` or `"Bottle"` or `"Frog"` or `"Funk"` or `"Glass"` or `"Hero"` or `"Morse"` or `"Ping"` or `"Pop"` or `"Purr"` or `"Sosumi"` or `"Submarine"` or `"Tink"` or `"custom_file"` or `"none"` | `"default"` | Notification sound preset. |51| `notifications.customSoundFilePath` | string | `""` | Local path to the custom notification sound file. |52| `notifications.command` | string | `""` | Optional shell command to run alongside notification delivery. |53| `notifications.hooksMode` | `"append"` or `"replace"` | `"append"` | Controls whether project-local notification hooks append to inherited hooks or replace them. |54| `notifications.hooks` | array<object> | `[]` | Composable shell hooks that receive notification policy JSON on stdin and return updated policy JSON on stdout. |55 56## sidebar57 58Sidebar content and metadata visibility from Settings > Sidebar.59 60| Key | Type | Default | Description |61|---|---|---|---|62| `sidebar.hideAllDetails` | boolean | `false` | Hide all per-workspace detail rows. |63| `sidebar.showWorkspaceDescription` | boolean | `true` | Show custom workspace descriptions in the sidebar. |64| `sidebar.branchLayout` | `"vertical"` or `"inline"` | `"vertical"` | Show git branch details stacked vertically or inline. |65| `sidebar.showNotificationMessage` | boolean | `true` | Show the latest notification text in the sidebar. |66| `sidebar.showBranchDirectory` | boolean | `true` | Show the workspace working directory. |67| `sidebar.showPullRequests` | boolean | `true` | Show pull request metadata in the sidebar. |68| `sidebar.makePullRequestsClickable` | boolean | `true` | Allow sidebar pull request metadata to open links when clicked. |69| `sidebar.openPullRequestLinksInCmuxBrowser` | boolean | `true` | Open sidebar pull request links in the embedded cmux browser. |70| `sidebar.openPortLinksInCmuxBrowser` | boolean | `true` | Open sidebar port links in the embedded cmux browser. |71| `sidebar.showSSH` | boolean | `true` | Show SSH connection details. |72| `sidebar.showPorts` | boolean | `true` | Show listening ports. |73| `sidebar.showLog` | boolean | `true` | Show recent log snippets. |74| `sidebar.showProgress` | boolean | `true` | Show progress indicators. |75| `sidebar.showCustomMetadata` | boolean | `true` | Show custom metadata pills. |76 77## workspaceColors78 79Workspace tab and badge colors from Settings > Workspace Colors.80 81| Key | Type | Default | Description |82|---|---|---|---|83| `workspaceColors.indicatorStyle` | `"leftRail"` or `"solidFill"` or `"rail"` or `"border"` or `"wash"` or `"lift"` or `"typography"` or `"washRail"` or `"blueWashColorRail"` | `"leftRail"` | Active workspace indicator style. Legacy aliases are accepted and normalized. |84| `workspaceColors.selectionColor` | colorHexOrNull | `null` | Override the selected workspace background color. |85| `workspaceColors.notificationBadgeColor` | colorHexOrNull | `null` | Override the unread notification badge color. |86| `workspaceColors.colors` | object | `{"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"}` | 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. |87| `workspaceColors.paletteOverrides` | object | `{}` | Legacy workspace color overrides for built-in palette names. Prefer workspaceColors.colors for new configs. |88| `workspaceColors.customColors` | array<colorHex> | `[]` | Legacy list of custom workspace colors. Prefer workspaceColors.colors for new configs. |89 90## sidebarAppearance91 92Sidebar tint settings from Settings > Sidebar Appearance.93 94| Key | Type | Default | Description |95|---|---|---|---|96| `sidebarAppearance.matchTerminalBackground` | boolean | `false` | Use the terminal background instead of the sidebar tint. |97| `sidebarAppearance.tintColor` | colorHex | `"#000000"` | Base sidebar tint color used when light/dark overrides are not set. |98| `sidebarAppearance.lightModeTintColor` | colorHexOrNull | `null` | Sidebar tint override for light appearance. |99| `sidebarAppearance.darkModeTintColor` | colorHexOrNull | `null` | Sidebar tint override for dark appearance. |100| `sidebarAppearance.tintOpacity` | number | `0.03` | 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`. |101 102## automation103 104Socket control and automation settings from Settings > Automation.105 106| Key | Type | Default | Description |107|---|---|---|---|108| `automation.socketControlMode` | `"off"` or `"cmuxOnly"` or `"automation"` or `"password"` or `"allowAll"` or `"openAccess"` or `"fullOpenAccess"` or `"notifications"` or `"full"` | `"cmuxOnly"` | Socket control mode. Legacy aliases are accepted and normalized. |109| `automation.socketPassword` | string or null | `""` | Password for password-mode socket access. Use null or an empty string to clear it. |110| `automation.claudeCodeIntegration` | boolean | `true` | Enable cmux integration hooks for Claude Code. |111| `automation.claudeBinaryPath` | string | `""` | Custom path to the claude binary. |112| `automation.cursorIntegration` | boolean | `true` | Enable cmux integration hooks for Cursor. |113| `automation.geminiIntegration` | boolean | `true` | Enable cmux integration hooks for Gemini. |114| `automation.portBase` | integer | `9100` | Starting value for workspace CMUX_PORT assignments. |115| `automation.portRange` | integer | `10` | Number of ports reserved per workspace. |116 117## browser118 119Embedded browser settings from Settings > Browser.120 121| Key | Type | Default | Description |122|---|---|---|---|123| `browser.defaultSearchEngine` | `"google"` or `"duckduckgo"` or `"bing"` or `"kagi"` or `"startpage"` | `"google"` | Default search engine for non-URL queries. |124| `browser.showSearchSuggestions` | boolean | `true` | Show omnibar search suggestions. |125| `browser.theme` | `"system"` or `"light"` or `"dark"` | `"system"` | Embedded browser theme. |126| `browser.defaultZoomLevel` | number | `1` | Default page zoom factor for newly opened browser pages (0.25–5; 1 = 100%). |127| `browser.openTerminalLinksInCmuxBrowser` | boolean | `true` | Open clicked terminal links in the embedded browser. |128| `browser.interceptTerminalOpenCommandInCmuxBrowser` | boolean | `true` | Intercept terminal open http(s) commands and route them through the embedded browser. |129| `browser.hostsToOpenInEmbeddedBrowser` | array<string> | `[]` | Allowlist of hosts that should stay inside the embedded browser. |130| `browser.urlsToAlwaysOpenExternally` | array<string> | `[]` | Rules that always open matching URLs in the system browser. |131| `browser.insecureHttpHostsAllowedInEmbeddedBrowser` | array<string> | `["localhost", "*.localhost", "127.0.0.1", "::1", "0.0.0.0", "*.localtest.me"]` | HTTP hosts allowed in the embedded browser without a warning prompt. |132| `browser.showImportHintOnBlankTabs` | boolean | `true` | Show the browser import hint on blank tabs. |133| `browser.reactGrabVersion` | string | `"0.1.29"` | Pinned react-grab version for the browser toolbar helper. |134 135## shortcuts136 137Keyboard shortcut settings from Settings > Keyboard Shortcuts.138 139| Key | Type | Default | Description |140|---|---|---|---|141| `shortcuts.bindings` | object | `{}` | Shortcut overrides keyed by cmux action id. Use a string for a single shortcut, an array for a chord, null, an empty string, none, clear, unbound, or disabled to unbind. |142