Skip to main content
Access cmux settings via ⌘, (Cmd+Comma) or cmux → Settings from the menu bar.

​
App

​
Appearance

Choose between light, dark, or system appearance mode.
  • System — Follows macOS system appearance
  • Light — Always use light mode
  • Dark — Always use dark mode
Select from multiple app icon variants. Changes apply immediately without relaunch.

​
Workspace behavior

Controls where new workspaces appear in the sidebar.
  • End — Add to the end of the list
  • After current — Insert after the active workspace
  • Start — Add to the beginning
When enabled, workspaces move to the top when they receive a notification.
Disable this if you rely on stable workspace positions for keyboard shortcuts (⌘1–⌘8).
Display the git branch and working directory for each workspace.
Display PR/MR status, number, and clickable links.Open sidebar PR links in cmux browser — When enabled, clicking PR links opens them in the embedded browser instead of your default browser.
Display detected listening ports for the active workspace. Useful for tracking dev servers.
Display the latest log/status message from cmux log commands.
Display progress bars set via cmux set_progress.
Display custom metadata from report_meta/set_status and report_meta_block socket commands.

​
Notifications

Show unread notification count on the app icon in the Dock and Cmd+Tab switcher.

​
Other

Share anonymized crash and usage data to help improve cmux. Changes take effect on next launch.
Show a confirmation dialog before quitting with ⌘Q. When disabled, ⌘Q quits immediately.
When enabled, the Command Palette rename action starts with all text selected. When disabled, the caret stays at the end.

​
Workspace colors

Choose how workspace colors appear in the sidebar:
  • Accent — Colored accent on the left edge
  • Underline — Colored line at the bottom
  • None — No color indicator
Modify the default workspace color palette. The settings panel shows:
  • Built-in color entries with hex values
  • Custom colors added via “Choose Custom Color…” from workspace context menus
  • Reset button to restore defaults
Each color entry shows:
  • Color picker for visual editing
  • Hex value in monospace font
  • Base color reference for built-in entries

​
Automation

​
Socket control mode

Controls access to the local Unix socket at /tmp/cmux.sock for programmatic control.
Disable the local control socket entirely.
Default. Only processes started inside cmux terminals can send commands.
Allow external local automation clients from this macOS user (no ancestry check).
Require socket authentication with a password stored in ~/Library/Application Support/cmux/socket-control-password.The settings panel provides:
  • Secure password field for entry
  • Set/Change button to save password
  • Clear button to remove password (when one exists)
  • Status messages for save/clear operations
External clients are blocked until a password is configured.
Makes the control socket world-readable/writable on this Mac and disables auth checks. Use only for local debugging.
Requires confirmation before enabling.
Environment variable overrides:
  • CMUX_SOCKET_ENABLE — 1/true/yes/on or 0/false/no/off
  • CMUX_SOCKET_MODE — off, cmuxOnly, automation, password, allowAll
  • CMUX_SOCKET_PATH — Custom socket path (requires CMUX_ALLOW_SOCKET_OVERRIDE=1 for stable/nightly builds)
  • CMUX_SOCKET_PASSWORD — Password for password mode (alternative to file storage)

​
Claude Code integration

When enabled, cmux wraps the claude command to inject session tracking and notification hooks. The sidebar shows Claude session status and notifications.Disable if you prefer to manage Claude Code hooks yourself.

​
Port ranges

Each workspace gets CMUX_PORT and CMUX_PORT_END environment variables with a dedicated port range. New terminals inherit these values.
  • Port Base — Starting port (default: 9100)
  • Port Range Size — Number of ports per workspace (default: 10)
Example: With base 9100 and range 10, workspace 1 gets ports 9100–9109, workspace 2 gets 9110–9119, etc.

​
Browser

Used by the browser address bar when input is not a URL.Available engines:
  • Google
  • DuckDuckGo
  • Bing
  • Yahoo
  • Ecosia
Enable/disable search suggestions in the address bar.

​
Appearance

  • System — Follows app and macOS appearance
  • Light — Forces light mode for compatible pages
  • Dark — Forces dark mode for compatible pages
When enabled, open https://... and open http://... commands open in the cmux browser (subject to host whitelist). When disabled, they always use your default browser.
Multi-line text field for host patterns. Applies to terminal link clicks and intercepted open https://... calls.
  • One host or wildcard per line
  • Examples: example.com, *.internal.example
  • Leave empty to open all hosts in cmux
  • Only matching hosts open in cmux; others use your default browser

​
Security

Controls which HTTP (non-HTTPS) hosts can open in cmux without a warning prompt.Default allowlist includes:
  • localhost
  • 127.0.0.1
  • ::1
  • 0.0.0.0
  • *.localtest.me
Add one host or wildcard per line. Click Save to apply changes.

​
History

View count of saved pages that appear in omnibar suggestions. Click Clear History… to remove all entries.

​
Keyboard shortcuts

All keyboard shortcuts are customizable. Click a shortcut value to record a new one. Press Esc to cancel recording.
See Keyboard shortcuts for the full list with default bindings.
Available actions:
  • Toggle Sidebar
  • New Workspace / Surface / Window
  • Close Workspace / Window
  • Show Notifications / Jump to Latest Unread
  • Next/Previous Workspace / Surface
  • Rename Workspace / Tab
  • Focus Pane (Left/Right/Up/Down)
  • Split Right/Down
  • Split Browser Right/Down
  • Toggle Pane Zoom
  • Open Browser / Folder
  • Toggle Browser Developer Tools
  • Show Browser JavaScript Console
  • Flash Focused Panel

​
Reset

Reset All Settings — Restores all in-app settings to factory defaults, including:
  • Appearance and theme
  • Socket control mode
  • Browser settings
  • Keyboard shortcuts
  • Sidebar display options
  • Workspace colors
This action cannot be undone. Your Ghostty configuration (~/.config/ghostty/config) is not affected.