cmux-customization

SKILL.md

cmux Customization

Use this skill for user-facing cmux customization. Keep the user's config intact, prefer schema-backed edits, and validate before reporting completion.

What Can Be Customized

Custom actions: define reusable actions in cmux.json. Actions can appear in Cmd+Shift+P, surface tab bars, shortcuts, and the plus-button right-click menu.

New workspace button: set ui.newWorkspace.action to replace the normal plus-button click, and ui.newWorkspace.contextMenu to control right-click actions. ui.newWorkspace.rightClick is accepted as an alias, but new examples should use contextMenu.

Surface tab bar buttons: set ui.surfaceTabBar.buttons to replace the default tab bar buttons. Include built-in IDs such as cmux.newTerminal, cmux.newBrowser, cmux.splitRight, and cmux.splitDown only when they should stay visible.

Workflows and layouts: use commands with workspace definitions to open a worktree, multiple checkouts, local services, browser previews, or SSH sessions in a deliberate split layout.

Dock controls: create .cmux/dock.json or ~/.config/cmux/dock.json for right-sidebar terminal controls such as logs, test watchers, git TUIs, dev servers, queues, or cmux feed tui --opentui.

Sidebar and app behavior: use cmux-settings for supported settings such as appearance, sidebar display, notification behavior, browser routing, automation, shortcuts, and new-workspace placement.

Workspace metadata: use the cmux CLI or cmux-workspace for workspace names, descriptions, colors, read state, and sidebar metadata updates.

Feed and notifications: use cmux hooks setup for Feed event sources, notification settings for delivery behavior, and notification hooks in cmux.json for filtering or post-processing banners.

Team presets and examples: use project-local .cmux/cmux.json and .cmux/dock.json to share worktree, SSH, review, dev, CI, and docs workspace patterns with a repo.

Import, export, and reset: back up the current config, apply the smallest diff, validate it, and keep a rollback path for user-owned customizations.

Terminal behavior: use Ghostty config for fonts, themes, cursor style, copy-on-select, shell integration, terminal keybindings, and terminal rendering.

Choose the Right Surface