# 설정

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](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](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}",
  //   "paneResizeStepPixels": 20,
  //   "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 기본 앱) 또는 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",
  //     "toggleFileEditorWordWrap": "opt+z",
  //     "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](https://cmux.com/ko/docs/custom-commands).

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

Accent for cmux-drawn chrome: the selected workspace, attention ring and pane flash, agent status, pane swap, canvas focus, and scroll markers. "cmux" uses cmux blue; "system" follows the macOS accent color and updates when it changes; a "#RRGGBB" hex uses that color in light and dark mode. workspaceColors.selectionColor and notifications.paneFlashColor still override their parts. Native controls always use the macOS accent.

Type

`string | unknown`

Default

`"cmux"`

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

새 창을 열 때 DEBUG 빌드에서만 사용하는 디스플레이 이름입니다. 빈 값은 시스템 기본값을 사용합니다.

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

Order used by Go to Workspace (Cmd-P): sidebar order, or most recently focused workspaces.

Type

`string`

Default

`"sidebar"`

Allowed values

`sidebar, recent`

`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

`false`

`app.paneResizeStepPixels`

Pixels moved per keypress when using pane-resize shortcuts. Accepts 1–200; defaults to 20. Changes apply immediately.

Type

`integer`

Default

`20`

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

When true, creating a split resizes the panes in that split's row or column to equal sizes. When false, a new split halves the pane it was created from.

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

Folder the Open Folder panel starts in, for example ~/code. Supports a leading ~. Leave empty to start in the active workspace's directory.

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가 직접 그리는 모든 요소(터미널 텍스트, 탭 제목, 사이드바, 설정, 오버레이, 창 테두리)의 확대 비율을 퍼센트로 지정합니다. 브라우저 서피스 안의 웹 페이지는 자체 크기를 유지합니다.

Type

`integer`

Default

`100`

`app.reorderOnNotification`

Automatic workspace reordering. true or "notifications" moves workspaces with new notifications toward the top. "agentActivity" also moves them when a prompt is sent or an agent finishes a turn, needs input, or fails, at most once per burst and never while the pointer is over the sidebar. false or "off" keeps the order stable.

Type

`boolean | string`

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도 boolean 대체값으로 계속 허용됩니다.

Type

`string`

Default

`"always"`

Allowed values

`always, dirty-only, never`

`app.warnBeforeQuit`

종료 확인을 위한 기존 boolean 대체값입니다. 새 구성에는 app.confirmQuit을 사용하세요.

Type

`boolean`

Default

`true`

`app.warnBeforeClosingTab`

Show a confirmation before closing a tab.

Type

`boolean`

Default

`true`

`app.warnBeforeClosingAgentSession`

Show a confirmation before closing an agent session while it is mid-turn.

Type

`boolean`

Default

`true`

`app.warnBeforeClosingTabXButton`

탭 닫기 버튼으로 탭을 닫기 전에 확인을 표시합니다.

Type

`boolean`

Default

`false`

`app.warnBeforeClosingWorkspace`

Show a confirmation before closing a workspace with a running process, or several workspaces at once. Pinned workspaces still ask when this is off.

Type

`boolean`

Default

`true`

`app.warnBeforeClosingWindow`

Show a confirmation before closing a window with a running process, or all of a window's workspaces at once.

Type

`boolean`

Default

`true`

`app.hideTabCloseButton`

창 영역 탭 막대에서 탭 닫기 버튼을 숨깁니다.

Type

`boolean`

Default

`false`

`app.tabBarVisibility`

창 영역이 탭 막대를 그리는 시점을 정합니다. "always"는 탭이 하나뿐인 창 영역에서도 그리고, "multiple-tabs"는 탭이 하나인 동안에는 숨겼다가 두 번째 탭이 열리면 그립니다. 미니멀 모드(app.minimalMode)에서는 항상 그립니다. 그곳에서는 맨 위 창 영역의 탭 막대가 창 제목 표시줄을 겸하기 때문입니다.

Type

`string`

Default

`"always"`

Allowed values

`always, multiple-tabs`

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

true(기본값)이면 Ghostty 테마나 터미널 색상이 설정되지 않은 경우 cmux가 모양에 따라 바뀌는 기본 팔레트를 제공합니다. 글꼴 및 기타 설정은 유지됩니다. false이면 Ghostty가 고정된 내장 팔레트를 사용합니다. theme = light:X,dark:Y를 포함한 명시적 테마 및 색상 설정이 항상 우선합니다.

Type

`boolean`

Default

`true`

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

마우스 휠이나 트랙패드 스크롤 이벤트 한 번에 터미널이 이동하는 거리를 조정합니다. 1보다 큰 값은 스크롤을 빠르게, 1보다 작은 값은 느리게 합니다.

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

Briefly show "Copied to clipboard" at the bottom of a terminal after selecting text copies it. Applies whether copyOnSelect or Ghostty's copy-on-select turned copying on. Copies made with a keyboard shortcut or by a program (OSC 52) never show it.

Type

`boolean`

Default

`false`

`terminal.reflowHardWrapOnCopy`

When true, copying terminal text also joins a line that exactly fills the terminal width onto the next line, undoing hard wraps a program inserted at the grid edge. Soft-wrapped rows are always joined.

Type

`boolean`

Default

`false`

`terminal.confirmUnsafePaste`

When true, a paste that Ghostty's clipboard-paste-protection flags as unsafe (for example, text with a line break going to a program that has not enabled bracketed paste) waits for confirmation in a sheet attached to the terminal's window. When false, cmux pastes it without asking. OSC 52 clipboard reads are not affected.

Type

`boolean`

Default

`false`

`terminal.textEditingGestures`

Replay macOS text-editing gestures as line-editor keys at the shell prompt: Command and Option arrow keys move by line and word, and Command and Option Delete kill by line and word. While a full-screen application (vim, less, htop, tmux) has the terminal on the alternate screen, it gets the keys as if gestures were off, unless textEditingGesturesInFullScreenApps is on. Ghostty's own bindings still apply there, so Command+Left sends Ctrl+A and Option+Left sends Esc b.

Type

`boolean`

Default

`false`

`terminal.textEditingCommandMovesByWord`

With textEditingGestures on, switch to a browser-style layout: Command arrow and Delete keys move and delete by word, like Option, and Control+Left/Right move to the start and end of the line. Every other Control chord, including Ctrl+W and Ctrl+C, still reaches the terminal. macOS reserves Control+Left/Right for switching Spaces by default; turn those off in System Settings > Keyboard > Keyboard Shortcuts > Mission Control for Control+arrows to reach cmux.

Type

`boolean`

Default

`false`

`terminal.textEditingGesturesInFullScreenApps`

Keep textEditingGestures active while a full-screen application has the terminal on the alternate screen. tmux, screen, and zellij keep the outer terminal on the alternate screen even at their shell prompt, so turn this on to use gestures inside a multiplexer. Applications that bind the gesture chords themselves then receive the translated keys.

Type

`boolean`

Default

`false`

`terminal.showPasswordInputIndicator`

Show a lock badge in the terminal corner while the foreground program has turned echo off for a password prompt (sudo, ssh, passwd, gpg). cmux draws the badge itself and never changes terminal text. Only prompts on the local terminal are detected: an ssh password prompt counts, but sudo run inside an ssh session does not. Changes apply to an open prompt at once.

Type

`boolean`

Default

`true`

`terminal.showPasswordInputDots`

When the password input badge is shown, also draw one dot per typed character. cmux keeps only a count, never the typed characters. Backspace removes a dot; Enter or echo turning back on clears them. Pasted text is not counted.

Type

`boolean`

Default

`false`

`terminal.showJumpToBottomButton`

Removed. cmux no longer shows a Jump to Bottom button in terminal panes, and ignores this key. It stays in the schema so existing configs still validate.

Type

`boolean`

Default

`none`

`terminal.predictiveLocalEcho`

Draw typed characters immediately in a terminal whose shell runs on another machine (cmux ssh, Cloud, remote tmux) when the link is slow, underlined until the remote echo confirms them, and withdraw them if the remote disagrees. Local terminals, password prompts and full-screen apps are excluded.

Type

`boolean`

Default

`true`

`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, under memory pressure (critical pressure from macOS or from the cmux app's own footprint, or cmux's total memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent 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.titleUpdates`

Terminal title update throttling and diagnostics.

Type

`object`

Default

`none`

`terminal.runawayMemoryGuardrail`

Per-pane process-tree memory monitoring.

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

Blink the pane flash twice instead of one short pulse.

Type

`boolean`

Default

`true`

`notifications.paneFlashOnTyping`

Flash the pane when terminal typing dismisses its notification.

Type

`boolean`

Default

`true`

`notifications.paneFlashThemeColor`

Use the terminal theme foreground for flashes when paneFlashColor is unset. Unread rings remain cmux blue.

Type

`boolean`

Default

`false`

`notifications.paneFlashColor`

Override the pane flash and unread notification ring color. Leave unset to use the accent from app.accentColor.

Type

`unknown`

Default

`null`

`notifications.soundWhenFocused`

알림을 보낸 패널이 이미 포커스된 상태여도 알림음을 재생합니다. 기본값은 꺼짐이며, 포커스된 패널은 링과 깜박임만 표시합니다.

Type

`boolean`

Default

`false`

`notifications.suppressOnlyFocusedSurface`

활성화하면 알림 배너는 해당 서피스가 정확히 포커스된 서피스일 때만 자동으로 철회됩니다. 현재 표시 중인 workspace에서 포커스되지 않은 서피스로 전달된 배너는 workspace가 표시될 때 철회되지 않고, 해당 서피스에 포커스할 때까지(또는 클릭/해제할 때까지) 계속 표시됩니다. 끄면 기존의 workspace 표시 여부 기반 철회 동작이 유지됩니다.

Type

`boolean`

Default

`false`

`notifications.suppressWhenAppFocused`

활성화하면 cmux가 활성 앱인 동안 포커스된 패널뿐 아니라 모든 알림에 대해 데스크톱 배너를 건너뜁니다. 알림은 계속 사이드바에 표시되고, 사운드와 사용자 지정 명령도 계속 실행되며, 휴대폰 전달은 바뀌지 않습니다. 끄면 cmux에 포커스가 있어도 다른 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`

에이전트가 유휴 상태로 입력을 기다릴 때(턴 종료 후 약 60초) 알림을 보냅니다. 이전 턴의 백그라운드 작업이 아직 남아 있는 동안에는 억제되므로 실행 중인 빌드나 감시자가 잘못된 대기 알림을 만들지 않습니다.

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

에이전트 및 알림 유형별 알림 소리 재정의입니다. 비어 있는 셀은 notifications.sound를 사용합니다.

Type

`object`

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

Sidebar font size in points. The legacy Ghostty key sidebar-font-size remains a fallback alias.

Type

`number`

Default

`12.5`

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

Override the workspace description text color in the sidebar.

Type

`unknown`

Default

`null`

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

Show git branch details stacked vertically when true, or inline when false. This boolean form is the canonical setting; branchLayout remains supported as a legacy alias.

Type

`boolean`

Default

`true`

`sidebar.stackBranchDirectory`

Render the git branch and working directory on separate lines instead of sharing one line.

Type

`boolean`

Default

`false`

`sidebar.pathLastSegmentOnly`

Truncate sidebar paths from the start, showing as much of the trailing path as fits with a leading …/. When false, full paths are abbreviated with ~/.

Type

`boolean`

Default

`false`

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

Git 브랜치 및 디렉터리 세부 정보와 관계없이 원격 워크스페이스 제목 옆에 Cloud 컴퓨터 및 기기 아이콘을 표시합니다.

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

Claude Code 또는 Codex 상태 항목에 코딩 에이전트 사용량을 덧붙입니다. 모델과 사용한 컨텍스트 창을 표시하고, Claude Code에서는 Anthropic이 공개한 정가를 기준으로 한 API 비용 추정치(메인 스레드와 서브에이전트)도 함께 표시합니다. 이 비용은 추정치이며 구독 청구액이 아닙니다. 배치 및 우선 처리 등급, 파트너 가격, 고속 모드, 서버 도구 요금은 반영하지 않습니다.

Type

`boolean`

Default

`false`

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

각 워크스페이스를 한 줄로 표시합니다. 제목 앞의 색상 아이콘 하나가 에이전트, 읽지 않음, 풀 리퀘스트 상태를 나타내며 에이전트 상태 행(예: 실행 중, 입력 필요), 브랜치 및 디렉터리 행, 풀 리퀘스트 행을 대신하고, 그 세부 정보는 아이콘의 도움말로 옮겨집니다. 다른 상태 항목은 자체 행을 유지합니다.

Type

`boolean`

Default

`false`

`sidebar.compactStatusIcons`

상태별로 compactAgentStatus 글리프를 대체하는 SF Symbol 이름입니다(예: {"terminal": "apple.terminal", "needsInput": "hand.raised.fill"}). 설정하지 않은 상태는 기본 기호를 사용하며, 표시할 수 없는 이름도 기본 기호로 돌아갑니다.

Type

`object`

Default

```
{}
```

`sidebar.activeTabIndicatorStyle`

Active workspace indicator style in the sidebar.

Type

`string`

Default

`"leftRail"`

Allowed values

`leftRail, solidFill, rail, border, wash, lift, typography, washRail, blueWashColorRail`

`sidebar.selectionColor`

Override the selected workspace background color in the sidebar.

Type

`unknown`

Default

`null`

`sidebar.notificationBadgeColor`

Override the unread notification badge color in the sidebar.

Type

`unknown`

Default

`null`

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

Show the selected workspace as a faint accent tint with a thin edge instead of a solid fill. A custom selectionColor still uses a solid fill.

Type

`boolean`

Default

`false`

`workspaceColors.brightenInDarkMode`

Lighten workspace colors in dark mode so they stay readable on a dark sidebar. false shows colors exactly as chosen. Applies to the solidFill indicator; leftRail always lightens its rail.

Type

`boolean`

Default

`true`

`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

`true`

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

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

Enable cmux integration hooks for Codex. When disabled, cmux no longer wraps the codex command but still tracks live Codex sessions it can observe.

Type

`boolean`

Default

`true`

`automation.canonicalAgentScratch`

Use a cmux-owned scratch directory for native agent panels, organized per session.

Type

`boolean`

Default

`false`

`automation.piIntegration`

Enable cmux integration hooks for Pi.

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

cmux가 실행한 에이전트의 턴이 재시도 가능한 업스트림 오류(모델 용량 초과, 과부하, 연결 끊김)로 끝나면 백오프를 적용해 \`continue\`를 보냅니다. 사람의 입력을 기다리는 턴은 재개하지 않습니다.

Type

`boolean`

Default

`true`

`automation.ampIntegration`

Amp용 cmux 훅을 켜거나 끕니다. 끄더라도 번들 플러그인은 설치된 상태로 남아 있으며 동작하지 않습니다.

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가 URL에 q=를 추가합니다.

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

Default page zoom factor applied to newly opened browser pages (1 = 100%). Zoom In, Zoom Out, and Actual Size still adjust each page.

Type

`number`

Default

`1`

`browser.discardHiddenWebViews`

Allow hidden browser tabs to release page memory. Scroll position, supported form input, and history are restored when recoverable.

Type

`boolean`

Default

`true`

`browser.hiddenWebViewDiscardMode`

How cmux picks hidden browser tabs to free. budget frees the tabs hidden longest once hidden tabs use more than hiddenWebViewMemoryBudgetMB; timer frees every tab hidden longer than hiddenWebViewDiscardDelaySeconds.

Type

`string`

Default

`"budget"`

Allowed values

`budget, timer`

`browser.hiddenWebViewMemoryBudgetMB`

Megabytes of memory hidden browser tabs may use before cmux frees the tabs hidden longest. Applies when hiddenWebViewDiscardMode is budget.

Type

`integer`

Default

`2048`

`browser.hiddenWebViewDiscardDelaySeconds`

Seconds a browser tab must stay hidden before cmux may free its page memory. In timer mode, every tab hidden this long is freed.

Type

`number`

Default

`300`

`browser.autoRestoreUnloadedPages`

Restore a browser page unloaded to save memory, or whose web process ended while hidden, as soon as its tab is shown. When false, the tab shows the page's last snapshot until you click Restore.

Type

`boolean`

Default

`true`

`browser.askWhereToSaveDownloads`

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

Type

`boolean`

Default

`false`

`browser.showLinkHoverURL`

포인터가 링크 위에 있거나 링크에 키보드 포커스가 있는 동안 브라우저 패널 왼쪽 하단에 링크의 대상 주소를 표시합니다.

Type

`boolean`

Default

`true`

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

내장 브라우저 탐색을 제한하는 호스트 또는 URL 패턴입니다. 설정 화면은 로컬 개발 오리진을 제안하며, 목록을 저장하면 선택적 제한이 활성화됩니다. 항목을 삭제하면 해당 오리진을 차단하고, 관리 정책이 없을 때 사용자 값을 비워 제한을 해제할 수 있습니다.

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 file editor settings.

`fileEditor.wordWrap`

편집기 너비보다 긴 줄을 소프트 줄 바꿈하여 가로 스크롤이 필요 없게 합니다.

Type

`boolean`

Default

`false`

`fileEditor.syntaxHighlighting`

내장 파일 편집기에서 연 코드에 언어별 색상을 적용합니다.

Type

`boolean`

Default

`true`

`fileEditor.lineNumbers`

내장 파일 편집기에서 본문 옆 열에 각 줄의 번호를 표시합니다.

Type

`boolean`

Default

`true`

`fileEditor.indentGuides`

내장 파일 편집기에서 들여쓰기 수준마다 얇은 세로선을 표시합니다.

Type

`boolean`

Default

`true`

`fileEditor.currentLineHighlight`

아무것도 선택하지 않았을 때 캐럿이 있는 줄에 색을 입힙니다.

Type

`boolean`

Default

`true`

`fileEditor.tabWidth`

탭 정지 하나가 차지하는 열 수입니다. 들여쓰기 가이드도 같은 간격을 사용합니다.

Type

`integer`

Default

`4`

### `fileExplorer`

오른쪽 사이드바 파일 탐색기(파일 트리) 설정입니다.

`fileExplorer.doubleClickAction`

파일 탐색기에서 파일을 더블클릭(또는 검색 결과에서 Return 키 입력)했을 때의 동작을 설정합니다. \`preview\`는 cmux 내장 파일 미리보기(기본값이자 기존 동작)를 엽니다. \`defaultEditor\`는 파일 형식의 macOS 기본 앱으로 엽니다. \`preferredEditor\`는 \`app.preferredEditor\` 명령으로 열고, 설정되지 않은 경우 기본 앱으로 대체합니다. 이 설정은 파일에만 적용되며, 디렉터리는 항상 펼치기/접기 동작을 하고, 로컬이 아닌(원격) 파일 탐색기는 항상 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, terminalAlternateScreen, 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](https://cmux.com/ko/docs/keyboard-shortcuts).

#### App

`openSettings`

Settings

Default file value

`cmd+,`

`openTeamPicker`

팀 선택기 열기

Default file value

`opt+shift+cmd+t`

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

`agentInbox`

에이전트 받은 편지함 표시

Default file value

`cmd+shift+i`

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

새 로컬 워크스페이스

Default file value

`cmd+n`

`newLocalWorkspace`

새 로컬 작업 공간원격 tmux 미러 작업 공간이 활성 상태일 때 로컬 작업 공간을 엽니다. 이때 새 작업 공간은 해당 작업 공간의 호스트에서 세션을 시작합니다

Default file value

`ctrl+opt+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`

`newCloudWorkspace`

새 클라우드 워크스페이스마지막으로 선택한 Cloud 워크스페이스의 머신을 사용하고, 없으면 오른쪽 사이드바의 첫 번째 머신을 사용합니다. 사용 가능한 머신이 없으면 New Cloud Machine을 엽니다

Default file value

`cmd+y`

`newCloudMachine`

새 클라우드 머신

Default file value

`shift+cmd+y`

`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+[`

`nextSidebarTabInGroup`

Next workspace in groupunbound by default; skips the group anchor and uses window-wide cycling when ungrouped

Default file value

`prevSidebarTabInGroup`

Previous workspace in groupunbound by default; skips the group anchor and uses window-wide cycling when ungrouped

Default file value

`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+]`

`focusHistoryLast`

Focus lastunbound by default; toggles between the current position and the one focus last left, so pressing it twice returns where you started

Default file value

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

`focusSidebar`

Focus the workspace sidebar↑/↓ select workspaces; Return or Esc returns to the terminal

Default file value

`ctrl+cmd+e`

`showWindowHints`

Click by hint: label the window's controlsType a label to click it, Shift+label to right-click; Esc cancels. Preview feature, off by default: turn on Click by Hint in Settings > Beta Features or from the command palette

Default file value

`cmd+j`

`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

#### 서피스

`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

`sizeTerminalToMyWindow`

Size shared terminal to my windowwhen a terminal is shared with phones or other clients, makes this Mac's window set its grid

Default file value

`ctrl+opt+cmd+=`

`pasteLastScreenshot`

마지막 스크린샷 붙여넣기기본값은 할당 안 됨. macOS 스크린샷 폴더(변경하지 않았다면 데스크탑)의 최신 스크린샷 경로를 포커스된 터미널에 넣고, 원격 워크스페이스에서는 먼저 업로드합니다

Default file value

`saveFilePreview`

Save file previewfocused text preview

Default file value

`cmd+s`

`toggleFileEditorWordWrap`

파일 편집기 자동 줄 바꿈 전환포커스된 파일 편집기

Default file value

`opt+z`

#### 분할 패널

`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

`focusPaneByNumber`

Focus pane 1…9

Default file value

`ctrl+cmd+1`

`splitRight`

Split right

Default file value

`cmd+d`

`splitDown`

Split down

Default file value

`cmd+shift+d`

`newPaneAutoLayout`

New pane (auto layout)retiles all panes like Zellij and cmux-tui Alt-n: the right column fills to four panes before a new column opens

Default file value

`ctrl+cmd+n`

`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+=`

`resize-pane-left`

Resize pane left

Default file value

`ctrl+shift+h`

`resize-pane-right`

Resize pane right

Default file value

`ctrl+shift+l`

`resize-pane-up`

Resize pane up

Default file value

`ctrl+shift+k`

`resize-pane-down`

Resize pane down

Default file value

`ctrl+shift+j`

#### 캔버스

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

#### Diff 뷰어

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

`diffViewerNextHunk`

Jump to next hunkfocused diff viewer

Default file value

`"n"`

`diffViewerPreviousHunk`

Jump to previous hunkfocused diff viewer

Default file value

`"p"`

`diffViewerToggleViewed`

현재 파일의 확인됨 상태 전환포커스된 diff 뷰어

Default file value

`"v"`

#### 찾기

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

`jumpToLastPrompt`

마지막으로 에이전트에 프롬프트를 보낸 서피스로 이동

Default file value

`cmd+shift+b`

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

`markAllNotificationsRead`

모든 알림을 읽음으로 표시기본적으로 할당되지 않음

Default file value

`clearAllNotifications`

모든 알림 지우기기본적으로 할당되지 않음

Default file value

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

Canonical: https://cmux.com/ko/docs/configuration

Documentation index: https://cmux.com/llms.txt