cmux Cheatsheet

Configuration

Use this cmux reference while you build software engineering projects, review code, or refresh the syntax you reach for most.

Which file owns what

cmux reads two configs and they do not overlap.

Concern	File
Font, theme, colors, cursor, `background-opacity`, `background-blur`, scrollback, terminal keybinds	`~/.config/ghostty/config`
Sidebar, tabs, notifications, browser, automation, app behavior, cmux shortcuts	`~/.config/cmux/cmux.json`

cmux settings path        # print the cmux.json paths
cmux settings             # open Settings
cmux config validate      # syntax check
cmux config doctor        # diagnose problems
cmux reload-config        # reload BOTH files, refresh terminals in place

Legacy fallbacks, read only for keys missing from cmux.json: ~/.config/cmux/settings.json and ~/Library/Application Support/com.cmuxterm.app/settings.json. Back up an existing cmux.json to a timestamped .bak before editing.

Schema and editor completion

cmux.json is JSON with a published JSON Schema, so point your editor at it.

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

curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json \
  -o ~/.config/cmux/cmux.schema.json

Top-level sections mirror the Settings panes: app, terminal, notifications, sidebar, sidebarAppearance, workspaceColors, automation, browser, shortcuts, markdown, canvas, fileEditor, fileExplorer, diffViewer, mobile, vault, computerUse, agentChat, plus actions, ui, commands, and workspaceGroups.

Sidebar

The sidebar is where the density lives, so most of these are about hiding rows.

Key	Default	Meaning
`hideAllDetails`	`false`	collapse every detail row
`showBranchDirectory`	`true`	show the working directory
`branchLayout`	`vertical`	`vertical` or inline branch details
`showPullRequests`	`true`	PR status and number
`makePullRequestsClickable`	`true`	click PR metadata to open it
`openPullRequestLinksInCmuxBrowser`	`true`	open in the embedded browser
`watchGitStatus`	`true`	watch files instead of polling
`showPorts`	`true`	listening ports
`showNotificationMessage`	`true`	latest notification text
`notificationMessageLineLimit`	`12`	max lines of that text
`showAgentActivity`	`true`	spinner while an agent is running
`showProgress` · `showLog` · `showSSH`	`true`	other metadata rows
`wrapWorkspaceTitles`	`false`	wrap instead of truncate
`rightMaxWidth`	dynamic	right sidebar width cap in points

App and terminal behavior

{
  "app": {
    "appearance": "system",
    "minimalMode": false,
    "newWorkspacePlacement": "afterCurrent",
    "workspaceInheritWorkingDirectory": true,
    "reorderOnNotification": true,
    "paneResizeStepPixels": 20,
    "globalFontMagnification": 100,
    "confirmQuit": "always",
    "warnBeforeClosingTab": true
  },
  "terminal": {
    "copyOnSelect": false,
    "showScrollBar": true,
    "scrollSpeed": 1.0,
    "autoResumeAgentSessions": true,
    "agentHibernation": { "enabled": false }
  }
}

Notable ones: minimalMode hides the workspace title bar and moves controls into the sidebar, keepWorkspaceOpenWhenClosingLastSurface stops a workspace from vanishing when its last tab closes, openSupportedFilesInCmux and openMarkdownInCmuxViewer control what ⌘-clicking a file path does, and preferredEditor is the fallback command when those are off. Terminal rendering is not here, it is Ghostty's job.

Automation and notifications

{
  "automation": {
    "socketControlMode": "cmuxOnly",
    "claudeCodeIntegration": true,
    "workspaceAutoNaming": false,
    "portBase": 9100,
    "portRange": 10
  },
  "notifications": {
    "agentTurnComplete": "whenIdle",
    "agentPermissionPrompt": true,
    "agentIdleReminder": true,
    "unreadPaneRing": true,
    "sound": "default"
  }
}

socketControlMode accepts off, cmuxOnly (default), notifications, automation, password, and allowAll. Per-agent integration switches exist for Claude, Amp, Cursor, Gemini, and Kiro. portBase and portRange decide the CMUX_PORT block each workspace gets.

Custom commands, dock, and sidebars

commands defines project-specific actions and workspace layouts that show up in the command palette, and ui wires buttons in the surface tab bar and the plus button.

Surface	Where
Custom commands and workspace definitions	`commands` in `cmux.json`
Right-sidebar dock controls	`.cmux/dock.json` in a repo, or `~/.config/cmux/dock.json`
Custom sidebars, beta	`~/.config/cmux/sidebars/*.swift`

cmux docs dock --json
python3 -m json.tool .cmux/dock.json     # validate before reloading
cmux sidebar validate
cmux reload-config

A per-repo .cmux/dock.json means a checkout can ship its own buttons, which is the cleanest way to give a team the same run and test controls without touching anyone's personal settings.