cmuxcmux/docs

Configuration

cmux reads terminal configuration from Ghostty config files. cmux-owned app settings also live in ~/.config/cmux/cmux.json, including shortcuts, automation, sidebar behavior, notifications, and browser preferences.

Config file locations

cmux looks for configuration in these locations (in order):

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

Create the config file if it doesn't exist:

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

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

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

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

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

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.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.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.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",
  "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, or a two-item array for a chord. Example: ["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+.
commandPalette

Command palette

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

Default file value
opt+cmd+f
reopenPreviousSession

Reopen previous session

Default file value
cmd+shift+o
quit

Quit cmux

Default file value
cmd+q

Workspaces

toggleSidebar

Toggle sidebar

Default file value
cmd+b
newTab

New workspace

Default file value
cmd+n
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+[
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
focusRightSidebar

Focus right sidebar

Default file value
cmd+shift+e
switchRightSidebarMode

Switch Files / Find / Sessions / Feed / Dockwhen the right sidebar is focused

Default file value
ctrl+1 / 2 / 3 / 4 / 5
navigateRightSidebarRows

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

Default file value
j / k
closeWorkspace

Close workspace

Default file value
cmd+shift+w

Surfaces

newSurface

New surface

Default file value
cmd+t
nextSurface

Next surface

Default file value
cmd+shift+]
prevSurface

Previous surface

Default file value
cmd+shift+[
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 closed browser panel

Default file value
cmd+shift+t
toggleTerminalCopyMode

Toggle terminal copy mode

Default file value
cmd+shift+m
saveFilePreview

Save file previewfocused text preview

Default file value
cmd+s

Split Panes

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

Browser

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
browserZoomIn

Zoom in

Default file value
cmd+=
browserZoomOut

Zoom out

Default file value
cmd+-
browserZoomReset

Actual size

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
toggleReactGrab

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

Default file value
cmd+shift+g

Find

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

Notifications

showNotifications

Show notifications

Default file value
cmd+i
jumpToUnread

Jump to latest unread

Default file value
cmd+shift+u
triggerFlash

Flash focused panel

Default file value
cmd+shift+h