Skip to main content
cmux is Ghostty compatible — it reads your existing ~/.config/ghostty/config for themes, fonts, and colors. Terminal rendering is powered by libghostty.

​
Configuration file locations

cmux searches for Ghostty configuration files in the following order (matching Ghostty’s macOS defaults):
  1. ~/.config/ghostty/config
  2. ~/.config/ghostty/config.ghostty
  3. ~/Library/Application Support/com.mitchellh.ghostty/config
  4. ~/Library/Application Support/com.mitchellh.ghostty/config.ghostty
The first file found is loaded. Subsequent files are ignored.
cmux loads configuration at startup and when you reload via ⌘⇧, (Cmd+Shift+Comma) or cmux → Reload Configuration.

​
Supported configuration options

cmux implements a subset of Ghostty’s configuration parser focused on visual appearance:

​
Fonts

font-family = "JetBrains Mono"
font-size = 14
  • font-family — Font name (default: Menlo)
  • font-size — Point size (default: 12)

​
Theme

theme = "dark:monokai,light:solarized light"
  • theme — Theme name or conditional theme selection
See Themes for detailed theme configuration.

​
Colors

You can override individual colors directly in the config: 
background = #272822
foreground = #fdfff1
cursor-color = #c0c1b5
cursor-text = #8d8e82
Color values must be in hex format: #RRGGBB

​
Transparency

background-opacity = 0.95
  • background-opacity — 0.0 (fully transparent) to 1.0 (opaque)
  • Default: 1.0

​
Split pane appearance

unfocused-split-opacity = 0.7
unfocused-split-fill = #000000
split-divider-color = #444444
  • unfocused-split-opacity — Opacity of unfocused panes (0.15–1.0, default: 0.7)
  • unfocused-split-fill — Overlay color for unfocused panes (default: background color)
  • split-divider-color — Color of dividers between panes (auto-computed if not set)

​
Scrollback

scrolling-limit = 10000
  • scrollback-limit — Number of lines to keep in scrollback (default: 10000)

​
Working directory

working-directory = ~/projects
  • working-directory — Default directory for new terminal sessions

​
Configuration reloading

Reload your configuration without restarting:
  • ⌘⇧, (Cmd+Shift+Comma)
  • Menu: cmux → Reload Configuration
This re-reads your Ghostty config files and applies changes to all active terminals.
Theme changes apply immediately. Font changes may require creating a new surface or workspace to take full effect.

​
Example configuration

Here’s a complete example combining common settings:
~/.config/ghostty/config
# Font
font-family = "JetBrains Mono"
font-size = 14

# Theme with light/dark variants
theme = dark:monokai,light:solarized light

# Transparency
background-opacity = 0.95

# Split pane appearance
unfocused-split-opacity = 0.8
split-divider-color = #444444

# Scrollback
scrolling-limit = 50000

# Working directory
working-directory = ~/projects

​
Environment variables

cmux sets the following Ghostty-compatible environment variables:
  • TERM=xterm-ghostty
  • TERM_PROGRAM=ghostty
  • GHOSTTY_RESOURCES_DIR — Path to Ghostty resources (themes, terminfo, etc.)
These are inherited by all terminal sessions.

​
Relationship to Ghostty

cmux uses libghostty for terminal rendering but is a separate application. Key differences:
  • cmux adds vertical tabs, notifications, and workspace management
  • cmux uses its own bundle ID (com.cmuxterm.app) and socket path (/tmp/cmux.sock)
  • Not all Ghostty config options are supported (see list above)
  • cmux-specific features are configured via in-app settings (⌘,)
You can run cmux and Ghostty side-by-side. They share the same config files but operate independently.

​
Troubleshooting

  1. Check that your theme file exists in ~/.config/ghostty/themes/ or the Ghostty bundle
  2. Verify the theme name matches exactly (case-sensitive)
  3. Try reloading configuration with ⌘⇧,
  4. Check the theme syntax — see Themes
  1. Verify the font is installed on your system
  2. Use the exact font family name (check Font Book.app)
  3. Reload configuration with ⌘⇧,
  4. Create a new workspace to see font changes
  1. Check for conflicting color definitions in your config
  2. Verify hex colors are in #RRGGBB format
  3. If using a theme, individual color overrides take precedence
  4. Try commenting out custom colors to test theme defaults
  1. Verify file path: ~/.config/ghostty/config expands correctly
  2. Check file permissions (should be readable)
  3. Look for syntax errors (invalid keys are silently ignored)
  4. Try restarting cmux as a last resort