cmux Customization
Keep the user's config intact, prefer schema-backed edits, and validate before reporting completion.
Choose the right surface
| Want to change |
Edit |
| App preferences (appearance, sidebar, notifications, browser routing, automation, shortcuts, new-workspace placement) |
~/.config/cmux/cmux.json via the cmux-settings helper |
| Custom actions, workspace layouts/commands, tab bar buttons, plus-button behavior, Command Palette entries, notification hooks |
~/.config/cmux/cmux.json globally or .cmux/cmux.json in the project |
Dock controls (right-sidebar terminals: logs, test watchers, git TUIs, dev servers, queues, cmux feed tui --opentui) |
.cmux/dock.json or ~/.config/cmux/dock.json; cmux docs dock when available |
| Terminal rendering and terminal keybindings (fonts, themes, cursor style, copy-on-select, shell integration) |
Ghostty config, usually ~/.config/ghostty/config |
| Workspace names, descriptions, colors, read state, sidebar metadata |
cmux CLI, see ../cmux-workspace/SKILL.md |
| Feed event sources |
cmux hooks setup |
Project-local .cmux/cmux.json and .cmux/dock.json let worktree, SSH, review, dev, CI, and docs patterns travel with the repo; project actions and commands override global entries with the same ID or name. Global app preferences do not belong there.
If a request can be handled by Ghostty config, say so and use Ghostty config instead of inventing cmux UI settings.
Key surfaces in cmux.json: actions (reusable, can appear in Cmd+Shift+P, surface tab bars, shortcuts, and the plus-button right-click menu), ui.newWorkspace.action (replaces the plus-button click) and ui.newWorkspace.contextMenu (right-click menu; ui.newWorkspace.rightClick is an accepted alias but new examples use contextMenu), ui.surfaceTabBar.buttons (replaces default tab bar buttons; include built-ins like cmux.newTerminal, cmux.newBrowser, cmux.splitRight, cmux.splitDown only when they should stay visible), and commands (workspace definitions with split layouts).
Workflow
Inspect existing config.
test -f ~/.config/cmux/cmux.json && sed -n '1,220p' ~/.config/cmux/cmux.json
test -f .cmux/cmux.json && sed -n '1,220p' .cmux/cmux.json
Pick global or project-local scope. Default to project-local for repo-specific commands, global for app preferences. Ask only when the choice changes behavior meaningfully.
Back up the target file when it already exists (applicable path only, no backup for a missing file).
stamp="$(date +%Y%m%d-%H%M%S)"
test -f ~/.config/cmux/cmux.json && cp -p ~/.config/cmux/cmux.json ~/.config/cmux/cmux.json."$stamp".bak
test -f .cmux/cmux.json && cp -p .cmux/cmux.json .cmux/cmux.json."$stamp".bak
For app settings and cmux-owned shortcuts, use the settings helper (~/.codex/skills/... if the user installed with skills.sh).
~/.agents/skills/cmux-settings/scripts/cmux-settings list-supported
~/.agents/skills/cmux-settings/scripts/cmux-settings set browser.openTerminalLinksInCmuxBrowser true
~/.agents/skills/cmux-settings/scripts/cmux-settings validate
For actions, UI wiring, workspace layouts, notification hooks, and Dock controls, edit the JSONC by hand and preserve unrelated sections (vault, rightSidebar, commands, actions, ui, notifications).
cmux reload-config.
Verify the configured entrypoint exists: read back the shortcut binding, or confirm the action ID and where it should appear.
Example: Command Palette action
Appears in Cmd+Shift+P unless palette is false.
{
"actions": {
"codex-new-tab": {
"type": "agent",
"agent": "codex",
"title": "Codex",
"subtitle": "Start Codex in this workspace",
"target": "newTabInCurrentPane",
"palette": true
}
}
}
For worktree agents, full-stack dev layouts, SSH devboxes, PR review workspaces, docs workspaces, tab bar buttons, and CI watch Dock controls, read references/examples.md. Load it when the user asks for examples, presets, templates, starter configs, or a known workflow shape.
Validation
- App settings:
cmux-settings validate.
- Keep valid JSONC, no duplicate keys.
- Parse
.cmux/dock.json or ~/.config/cmux/dock.json with a JSON parser before reporting completion.
cmux reload-config when the CLI is available.
- Confirm the exact user-facing result: action title, shortcut, plus-button behavior, context-menu entry, or tab bar placement.
Rules
- Do not overwrite a whole top-level config section unless you own the full section.
- Do not store secrets in actions, commands, or prompts. Use environment variables or the user's secret manager.
- Do not use sleeps or timing workarounds in generated commands.
- Do not add a cmux setting for behavior Ghostty already owns.
- Keep labels short enough for menus, buttons, and the Command Palette.
1---
2name: cmux-customization
3description: "Customize cmux for an end user. Use when changing cmux.json actions, custom commands, workspace layouts, plus-button behavior, surface tab bar buttons, Command Palette entries, Dock controls, sidebar and app settings, shortcuts, notifications, browser routing, examples-library presets, or Ghostty-backed terminal preferences."
4metadata:
5 source: https://skillmd.com/skills/manaflow-ai/cmux-customization
6---
7
8# cmux Customization
9
10Keep the user's config intact, prefer schema-backed edits, and validate before reporting completion.
11
12## Choose the right surface
13
14| Want to change | Edit |
15|---|---|
16| App preferences (appearance, sidebar, notifications, browser routing, automation, shortcuts, new-workspace placement) | `~/.config/cmux/cmux.json` via the `cmux-settings` helper |
17| Custom actions, workspace layouts/commands, tab bar buttons, plus-button behavior, Command Palette entries, notification hooks | `~/.config/cmux/cmux.json` globally or `.cmux/cmux.json` in the project |
18| Dock controls (right-sidebar terminals: logs, test watchers, git TUIs, dev servers, queues, `cmux feed tui --opentui`) | `.cmux/dock.json` or `~/.config/cmux/dock.json`; `cmux docs dock` when available |
19| Terminal rendering and terminal keybindings (fonts, themes, cursor style, copy-on-select, shell integration) | Ghostty config, usually `~/.config/ghostty/config` |
20| Workspace names, descriptions, colors, read state, sidebar metadata | cmux CLI, see [../cmux-workspace/SKILL.md](../cmux-workspace/SKILL.md) |
21| Feed event sources | `cmux hooks setup` |
22
23Project-local `.cmux/cmux.json` and `.cmux/dock.json` let worktree, SSH, review, dev, CI, and docs patterns travel with the repo; project actions and commands override global entries with the same ID or name. Global app preferences do not belong there.
24
25If a request can be handled by Ghostty config, say so and use Ghostty config instead of inventing cmux UI settings.
26
27Key surfaces in `cmux.json`: `actions` (reusable, can appear in Cmd+Shift+P, surface tab bars, shortcuts, and the plus-button right-click menu), `ui.newWorkspace.action` (replaces the plus-button click) and `ui.newWorkspace.contextMenu` (right-click menu; `ui.newWorkspace.rightClick` is an accepted alias but new examples use `contextMenu`), `ui.surfaceTabBar.buttons` (replaces default tab bar buttons; include built-ins like `cmux.newTerminal`, `cmux.newBrowser`, `cmux.splitRight`, `cmux.splitDown` only when they should stay visible), and `commands` (workspace definitions with split layouts).
28
29## Workflow
30
311. Inspect existing config.
32
33 ```bash
34 test -f ~/.config/cmux/cmux.json && sed -n '1,220p' ~/.config/cmux/cmux.json
35 test -f .cmux/cmux.json && sed -n '1,220p' .cmux/cmux.json
36 ```
37
382. Pick global or project-local scope. Default to project-local for repo-specific commands, global for app preferences. Ask only when the choice changes behavior meaningfully.
393. Back up the target file when it already exists (applicable path only, no backup for a missing file).
40
41 ```bash
42 stamp="$(date +%Y%m%d-%H%M%S)"
43 test -f ~/.config/cmux/cmux.json && cp -p ~/.config/cmux/cmux.json ~/.config/cmux/cmux.json."$stamp".bak
44 test -f .cmux/cmux.json && cp -p .cmux/cmux.json .cmux/cmux.json."$stamp".bak
45 ```
46
474. For app settings and cmux-owned shortcuts, use the settings helper (`~/.codex/skills/...` if the user installed with `skills.sh`).
48
49 ```bash
50 ~/.agents/skills/cmux-settings/scripts/cmux-settings list-supported
51 ~/.agents/skills/cmux-settings/scripts/cmux-settings set browser.openTerminalLinksInCmuxBrowser true
52 ~/.agents/skills/cmux-settings/scripts/cmux-settings validate
53 ```
54
555. For actions, UI wiring, workspace layouts, notification hooks, and Dock controls, edit the JSONC by hand and preserve unrelated sections (`vault`, `rightSidebar`, `commands`, `actions`, `ui`, `notifications`).
566. `cmux reload-config`.
577. Verify the configured entrypoint exists: read back the shortcut binding, or confirm the action ID and where it should appear.
58
59## Example: Command Palette action
60
61Appears in Cmd+Shift+P unless `palette` is false.
62
63```json
64{
65 "actions": {
66 "codex-new-tab": {
67 "type": "agent",
68 "agent": "codex",
69 "title": "Codex",
70 "subtitle": "Start Codex in this workspace",
71 "target": "newTabInCurrentPane",
72 "palette": true
73 }
74 }
75}
76```
77
78For worktree agents, full-stack dev layouts, SSH devboxes, PR review workspaces, docs workspaces, tab bar buttons, and CI watch Dock controls, read [references/examples.md](references/examples.md). Load it when the user asks for examples, presets, templates, starter configs, or a known workflow shape.
79
80## Validation
81
82- App settings: `cmux-settings validate`.
83- Keep valid JSONC, no duplicate keys.
84- Parse `.cmux/dock.json` or `~/.config/cmux/dock.json` with a JSON parser before reporting completion.
85- `cmux reload-config` when the CLI is available.
86- Confirm the exact user-facing result: action title, shortcut, plus-button behavior, context-menu entry, or tab bar placement.
87
88## Rules
89
90- Do not overwrite a whole top-level config section unless you own the full section.
91- Do not store secrets in actions, commands, or prompts. Use environment variables or the user's secret manager.
92- Do not use sleeps or timing workarounds in generated commands.
93- Do not add a cmux setting for behavior Ghostty already owns.
94- Keep labels short enough for menus, buttons, and the Command Palette.