Skip to main content
cmux supports Ghostty’s theme system, allowing you to use any Ghostty-compatible theme file.

​
Setting a theme

Add a theme line to your ~/.config/ghostty/config: 
theme = monokai
Reload configuration with ⌘⇧, to apply changes.

​
Conditional themes (light/dark)

Specify different themes for light and dark mode: 
theme = dark:monokai,light:solarized light
The syntax is: 
theme = dark:<dark-theme>,light:<light-theme>
cmux automatically switches themes when macOS appearance changes or when you change the app theme in Settings.
You can also specify a single theme without prefixes as a fallback:
theme = tokyo-night,dark:tokyo-night-storm,light:tokyo-night-day
The unprefixed theme is used if neither dark nor light variant matches.

​
Theme file locations

cmux searches for theme files in the following order:
  1. $GHOSTTY_RESOURCES_DIR/themes/<theme-name> (if set)
  2. App bundle: cmux.app/Contents/Resources/ghostty/themes/<theme-name>
  3. $XDG_DATA_DIRS/ghostty/themes/<theme-name> (colon-separated paths)
  4. /Applications/Ghostty.app/Contents/Resources/ghostty/themes/<theme-name>
  5. ~/.config/ghostty/themes/<theme-name>
  6. ~/Library/Application Support/com.mitchellh.ghostty/themes/<theme-name>
cmux supports Ghostty’s theme naming conventions:
  • monokai → searches for file named monokai
  • Monokai Pro → searches for Monokai Pro
  • builtin monokai → strips “builtin” prefix → searches for monokai
  • monokai (builtin) → strips “(builtin)” suffix → searches for monokai
Theme name resolution is case-sensitive.

​
Theme file format

Theme files use the same syntax as Ghostty config files: 
# Basic colors
background = #272822
foreground = #fdfff1
cursor-color = #c0c1b5
cursor-text = #8d8e82
selection-background = #57584f
selection-foreground = #fdfff1

# 16-color palette
palette = 0=#272822   # black
palette = 1=#f92672   # red
palette = 2=#a6e22e   # green
palette = 3=#f4bf75   # yellow
palette = 4=#66d9ef   # blue
palette = 5=#ae81ff   # magenta
palette = 6=#a1efe4   # cyan
palette = 7=#f8f8f2   # white
palette = 8=#75715e   # bright black
palette = 9=#f92672   # bright red
palette = 10=#a6e22e  # bright green
palette = 11=#f4bf75  # bright yellow
palette = 12=#66d9ef  # bright blue
palette = 13=#ae81ff  # bright magenta
palette = 14=#a1efe4  # bright cyan
palette = 15=#f9f8f5  # bright white

​
Required fields

  • background — Terminal background color
  • foreground — Default text color
  • palette entries (0–15) — ANSI color palette

​
Optional fields

  • cursor-color — Cursor fill color (defaults to foreground)
  • cursor-text — Text color under cursor (defaults to background)
  • selection-background — Background color for selected text
  • selection-foreground — Text color for selected text
  • background-opacity — Transparency (0.0–1.0)

​
Creating custom themes

  1. Create ~/.config/ghostty/themes/ directory: 
    mkdir -p ~/.config/ghostty/themes
  2. Create a theme file (e.g., my-theme): 
    touch ~/.config/ghostty/themes/my-theme
  3. Edit the file with your colors:
    ~/.config/ghostty/themes/my-theme
    background = #1e1e2e
foreground = #cdd6f4
cursor-color = #f5e0dc

palette = 0=#45475a
palette = 1=#f38ba8
# ... add all 16 palette entries
  4. Reference it in your config:
    ~/.config/ghostty/config
    theme = my-theme
  5. Reload configuration: ⌘⇧,
You can also copy existing themes from Ghostty’s theme directory as starting points.

​
Compatibility aliases

cmux includes compatibility aliases for popular themes:
  • solarized light → tries iTerm2 Solarized Light as fallback
  • solarized dark → tries iTerm2 Solarized Dark as fallback
This improves compatibility with theme collections that use different naming conventions.

​
Overriding theme colors

You can override specific colors from a theme in your main config file:
~/.config/ghostty/config
theme = monokai

# Override background with transparency
background = #272822
background-opacity = 0.95

# Override cursor colors
cursor-color = #ff6188
cursor-text = #2d2a2e
Config file color definitions take precedence over theme file values.

​
Built-in themes

If you have Ghostty installed at /Applications/Ghostty.app, cmux can access its bundled themes:
  • 3024 Day / Night
  • Alabaster
  • Argonaut
  • Ashes
  • Atom One Dark / Light
  • Breeze
  • Builtin Tango variants
  • Catppuccin (Frappe, Latte, Macchiato, Mocha)
  • Dracula
  • Flexoki (Dark, Light)
  • Gruvbox (Dark, Light)
  • Nord
  • One Half (Dark, Light)
  • Tokyo Night (Day, Moon, Night, Storm)
  • … and many more
Check /Applications/Ghostty.app/Contents/Resources/ghostty/themes/ for the complete list.

​
Terminal color testing

Test your theme with this snippet: 
# 16 ANSI colors
for i in {0..15}; do
  printf "\e[48;5;${i}m  \e[0m"
  [ $((($i + 1) % 8)) -eq 0 ] && echo
done
echo

# 256 color palette preview
for i in {16..255}; do
  printf "\e[48;5;${i}m  \e[0m"
  [ $((($i + 1) % 16)) -eq 0 ] && echo
done
echo
This displays all palette colors in your current terminal.

​
Troubleshooting

  1. Verify the theme file exists: 
    ls ~/.config/ghostty/themes/
  2. Check the theme name matches exactly (case-sensitive)
  3. Try the full path: 
    theme = ~/.config/ghostty/themes/my-theme
  4. Look for the theme in Ghostty bundle: 
    ls /Applications/Ghostty.app/Contents/Resources/ghostty/themes/
  1. Verify all palette entries (0–15) are defined
  2. Check hex format: must be #RRGGBB (6 digits)
  3. Reload config with ⌘⇧,
  4. Check for conflicting color definitions in main config
  5. Try a known working theme (e.g., monokai) to isolate the issue
  1. Verify syntax: theme = dark:theme1,light:theme2
  2. Check both theme files exist
  3. Test by changing app theme in Settings (⌘,)
  4. Try using theme = system in a theme file to delegate to main config
Background transparency requires:
  1. background-opacity set to less than 1.0
  2. macOS compositing enabled (should be default)
  3. No background image set in the theme
If still not working, try:
background-opacity = 0.95
background = #000000

​
Resources