cmux-customization

An end-user customization skill for cmux that edits the application's configuration safely. It covers a broad surface: custom actions in cmux.json (which can appear in the Cmd+Shift+P Command Palette, surface tab bars, shortcuts, and the plus-button right-click menu), the new-workspace plus-button behavior (ui.newWorkspace.action and ui.newWorkspace.contextMenu), surface tab bar buttons, workspace layouts and workflows built from commands, Dock controls in .cmux/dock.json, sidebar and app settings, notifications and feed hooks, workspace metadata, team presets, and Ghostty-backed terminal preferences. Its guiding principles are to keep the user's config intact, prefer schema-backed edits, and validate before reporting completion.

Choosing the right surface is a central concern. App preferences such as appearance, sidebar, notifications, browser routing, automation, and shortcuts are managed through the cmux-settings helper against the global ~/.config/cmux/cmux.json. Actions, UI wiring, workspace layouts, tab bar buttons, plus-button behavior, and Command Palette entries are edited in the global cmux.json or a project-local .cmux/cmux.json, where project-local entries override global ones with the same ID or name. Dock controls live in dock.json, and terminal rendering and terminal keybindings (fonts, cursor style, copy-on-select, shell integration, themes) belong in the Ghostty config rather than invented cmux UI settings.

The workflow is deliberately careful: inspect the existing config first, pick global or project-local scope, back up the target file with a timestamped copy before editing, apply the smallest diff while preserving unrelated sections such as vault, rightSidebar, commands, actions, ui, and notifications, then run cmux reload-config and verify the configured entrypoint exists. A reusable examples library covers worktree agents, full-stack dev layouts, SSH devboxes, PR review workspaces, and CI watches.