設定

cmuxはターミナル設定をGhosttyの設定ファイルから読み込みます。cmux管理のアプリ設定も ~/.config/cmux/cmux.json で管理でき、ショートカット、自動化、サイドバー、通知、ブラウザ設定を含みます。

設定ファイルの場所

cmuxは以下の場所から設定を検索します（順番に）：

~/.config/ghostty/config
~/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
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.

~/.config/cmux/cmux.json
.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, and UI action wiring, 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",
  //   "iMessageMode": true
  // },

  // "terminal": {
  //   "showScrollBar": false,
  //   "autoResumeAgentSessions": true
  // },

  // "browser": {
  //   "openTerminalLinksInCmuxBrowser": true,
  //   "hostsToOpenInEmbeddedBrowser": ["localhost", "*.internal.example"]
  // },

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

  // "shortcuts": {
  //   "bindings": {
  //     "toggleSidebar": "cmd+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.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.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.preferredEditor

Custom editor command used by cmux where applicable. Leave empty to use the default.

Type: string
Default: ""

app.openMarkdownInCmuxViewer

When enabled, Cmd-clicking .md/.markdown/.mkd/.mdx files in the terminal opens them in the cmux markdown viewer panel (with live reload) instead of the preferred editor.

Type: boolean
Default: false

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

Show a confirmation before quitting cmux.

Type: boolean
Default: true

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

Automatically run agent resume commands for restored terminal sessions when cmux reopens after quit.

Type: boolean
Default: true

`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.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: ""

`sidebar`

Sidebar content and metadata visibility from Settings > Sidebar.

sidebar.hideAllDetails

Hide all per-workspace detail rows.

Type: boolean
Default: false

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

Show the workspace working directory.

Type: boolean
Default: true

sidebar.showPullRequests

Show pull request metadata in the sidebar.

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

Show custom metadata pills.

Type: boolean
Default: true

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

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

Enable cmux integration hooks for Cursor.

Type: boolean
Default: true

automation.geminiIntegration

Enable cmux integration hooks for Gemini.

Type: boolean
Default: true

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

`browser`

Embedded browser settings from Settings > Browser.

browser.defaultSearchEngine

Default search engine for non-URL queries.

Type: string
Default: "google"
Allowed values: google, duckduckgo, bing, kagi, startpage

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

`shortcuts`

Keyboard shortcut settings from Settings > Keyboard Shortcuts.

shortcuts.showModifierHoldHints

Show shortcut hint pills while holding Cmd or Ctrl.

Type: boolean
Default: true

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

アプリ

openSettings

設定

Default file value

cmd+,

reloadConfiguration

構成を再読み込み

Default file value

cmd+shift+,

showHideAllWindows

すべてのcmuxウインドウを表示/非表示システム全体のホットキー

Default file value

ctrl+opt+cmd+.

commandPalette

コマンドパレット

Default file value

cmd+shift+p

commandPaletteNext

コマンドパレットの次の結果コマンドパレットを開いている間

Default file value

ctrl+n

commandPalettePrevious

コマンドパレットの前の結果コマンドパレットを開いている間

Default file value

ctrl+p

newWindow

新規ウインドウ

Default file value

cmd+shift+n

closeWindow

ウインドウを閉じる

Default file value

ctrl+cmd+w

toggleFullScreen

フルスクリーンを切り替え

Default file value

ctrl+cmd+f

sendFeedback

フィードバックを送信

Default file value

opt+cmd+f

reopenPreviousSession

前回のセッションを再度開く

Default file value

cmd+shift+o

quit

cmuxを終了

Default file value

cmd+q

ワークスペース

toggleSidebar

サイドバーを切り替え

Default file value

cmd+b

newTab

新規ワークスペース

Default file value

cmd+n

openFolder

フォルダを開く

Default file value

cmd+o

goToWorkspace

ワークスペースへ移動ワークスペーススイッチャー

Default file value

cmd+p

nextSidebarTab

次のワークスペース

Default file value

ctrl+cmd+]

prevSidebarTab

前のワークスペース

Default file value

ctrl+cmd+[

selectWorkspaceByNumber

ワークスペース1…9を選択

Default file value

cmd+1

renameWorkspace

ワークスペース名を変更

Default file value

cmd+shift+r

editWorkspaceDescription

ワークスペースの説明を編集

Default file value

opt+cmd+e

focusRightSidebar

右サイドバーを切り替え

Default file value

opt+cmd+b

toggleFileExplorer

ファイルエクスプローラを開く

Default file value

cmd+shift+e

navigateRightSidebarRows

フォーカス中のサイドバー行を移動ファイルでは H/L でフォルダを折りたたみ/展開します。検索は / で開始します。

Default file value

j / k

closeWorkspace

ワークスペースを閉じる

Default file value

cmd+shift+w

サーフェス

newSurface

新規サーフェス

Default file value

cmd+t

nextSurface

次のサーフェス

Default file value

cmd+shift+]

prevSurface

前のサーフェス

Default file value

cmd+shift+[

selectSurfaceByNumber

サーフェス1…9を選択

Default file value

ctrl+1

renameTab

タブ名を変更

Default file value

cmd+r

closeTab

タブを閉じる

Default file value

cmd+w

closeOtherTabsInPane

ペイン内の他のタブを閉じる

Default file value

opt+cmd+t

reopenClosedBrowserPanel

閉じたブラウザパネルを再度開く

Default file value

cmd+shift+t

toggleTerminalCopyMode

ターミナルコピーモードを切り替え

Default file value

cmd+shift+m

saveFilePreview

ファイルプレビューを保存フォーカス中のテキストプレビュー

Default file value

cmd+s

分割ペイン

focusLeft

左のペインにフォーカス

Default file value

opt+cmd+left

focusRight

右のペインにフォーカス

Default file value

opt+cmd+right

focusUp

上のペインにフォーカス

Default file value

opt+cmd+up

focusDown

下のペインにフォーカス

Default file value

opt+cmd+down

splitRight

右に分割

Default file value

cmd+d

splitDown

下に分割

Default file value

cmd+shift+d

splitBrowserRight

右にブラウザ分割

Default file value

opt+cmd+d

splitBrowserDown

下にブラウザ分割

Default file value

opt+cmd+shift+d

toggleSplitZoom

ペインズームを切り替え

Default file value

cmd+shift+enter

equalizeSplits

分割サイズを均等にする

Default file value

ctrl+cmd+=

ブラウザ

openBrowser

ブラウザを開く

Default file value

cmd+shift+l

focusBrowserAddressBar

アドレスバーにフォーカス

Default file value

cmd+l

browserBack

戻る

Default file value

cmd+[

browserForward

進む

Default file value

cmd+]

browserReload

ページを再読み込みフォーカス中のブラウザ

Default file value

cmd+r

browserZoomIn

拡大

Default file value

cmd+=

browserZoomOut

縮小

Default file value

cmd+-

browserZoomReset

実寸表示

Default file value

cmd+0

toggleBrowserDeveloperTools

ブラウザ開発者ツールを切り替え

Default file value

opt+cmd+i

showBrowserJavaScriptConsole

ブラウザJavaScriptコンソールを表示

Default file value

opt+cmd+c

toggleReactGrab

React Grabを切り替えフォーカス中のブラウザ、またはターミナルにフォーカスがあるときは唯一のブラウザペイン

Default file value

cmd+shift+g

検索

find

検索

Default file value

cmd+f

findInDirectory

ディレクトリ内を検索

Default file value

cmd+shift+f

findNext

次を検索

Default file value

cmd+g

findPrevious

前を検索

Default file value

opt+cmd+g

hideFind

検索バーを隠す

Default file value

opt+cmd+shift+f

useSelectionForFind

選択範囲で検索

Default file value

cmd+e

通知

showNotifications

通知を表示

Default file value

cmd+i

jumpToUnread