How cmux Integrates with Ghostty Configuration Files and Themes

cmux embeds the Ghostty terminal engine and consumes the same configuration file format, using the GhosttyConfig struct in Sources/GhosttyConfig.swift to load settings, resolve themes, and drive the application’s UI styling.

cmux is a terminal multiplexer built around the Ghostty rendering engine. Because it embeds Ghostty directly, it reuses the exact configuration file format and theme resolution logic that Ghostty users already know. The integration happens primarily through the GhosttyConfig class, which bridges raw Ghostty configuration files with cmux-specific UI components like split dividers and sidebar backgrounds.

Loading Ghostty Configuration in cmux

The Entry Point: GhosttyConfig.load()

When cmux launches, the application delegate and terminal views invoke a single convenience method to bootstrap the configuration:

let config = GhosttyConfig.load()

According to the source code in AppDelegate.swift at line 6417 and TerminalView.swift at line 27, this call is the standard entry point for the entire application. The load() method handles color scheme detection, caching, and disk access in one synchronous operation.

Configuration Search Paths

The loadFromDisk method (referenced in GhosttyConfig.swift lines 70-74) constructs a prioritized search list that mirrors Ghostty’s native behavior while adding cmux-specific locations. The resolution order is:

let configPaths = [
    "~/.config/ghostty/config",
    "~/.config/ghostty/config.ghostty",
    "~/Library/Application Support/com.mitchellh.ghostty/config",
    "~/Library/Application Support/com.mitchellh.ghostty/config.ghostty",
] + cmuxConfigPaths()

The cmuxConfigPaths() function (lines 98-141) appends additional directories relative to the running cmux bundle’s Application Support folder. This allows users to ship custom configuration files alongside the cmux application binary. Each candidate path is validated via readConfigFile and parsed only if it contains non-empty data (lines 103-108).

Caching and Performance

To avoid reparsing configuration files on every terminal instantiation, GhosttyConfig.load() checks an in-process cache via cachedLoad (lines 83-87). If a valid cached entry exists for the current color scheme preference, the method returns immediately; otherwise, it falls back to loadFromDisk and populates the cache for subsequent calls.

Parsing Ghostty Configuration Syntax

Key-Value Parsing

The parse(_:) method (lines 25-112 in GhosttyConfig.swift) iterates through the configuration file line-by-line, handling Ghostty’s standard key-value syntax such as font-family=Menlo or theme=Solarized Dark. This parser supports the full Ghostty configuration grammar, ensuring compatibility with existing user dotfiles.

cmux-Specific UI Overrides

While parsing, cmux extracts values specific to its own interface. The struct stores properties like:

• unfocusedSplitOpacity – Controls dimming of inactive terminal splits
• sidebarBackground – Defines the color of the side panel

These values are resolved after parsing via resolveSidebarBackground (lines 44-60) and propagated to the rest of the application through applySidebarAppearanceToUserDefaults (lines 62-90), which writes select values to UserDefaults for UI components that require standard AppKit storage.

Resolving and Loading Ghostty Themes

Theme Name Resolution

When the parsed configuration contains a theme key, loadTheme(_:) is invoked (lines 109-117). The helper resolveThemeName(from:preferredColorScheme:) (lines 53-115) handles Ghostty’s light/dark theme syntax. For example, a configuration containing theme = light:Solarized Light,dark:Solarized Dark automatically selects the appropriate variant based on the current macOS appearance (currentColorSchemePreference).

Theme Search Path Resolution

The themeSearchPaths(forThemeName:environment:bundleResourceURL:) method (lines 68-94) builds an ordered list of directories where theme files might reside:

1. The directory specified by the GHOSTTY_RESOURCES_DIR environment variable
2. The app bundle’s ghostty/themes/<theme> folder
3. XDG data directories (XDG_DATA_DIRS)
4. Standard user locations such as ~/Library/Application Support/com.mitchellh.ghostty/themes

Each path is expanded and deduplicated via appendUniquePath (lines 75-82) before being returned as an ordered array.

Merging Theme Colors with User Config

The loadTheme implementation iterates over candidate theme names and search paths, reading the first valid file using String(contentsOfFile:) and feeding the contents back into the parse method (lines 132-141). This merges the theme’s color definitions with any user-provided overrides from the main configuration file, allowing granular customization of palette values while maintaining the base theme structure.

Applying Configuration to the cmux UI

Once loaded, the configuration struct drives the visual presentation of the workspace. WorkspaceContentView.swift (lines 594-614) consumes properties such as unfocusedSplitOverlayOpacity and resolvedSplitDividerColor to style terminal panels and split dividers. The sidebar background color is resolved dynamically based on the current color scheme and applied to the interface layers directly.

Summary

• cmux uses the GhosttyConfig struct in Sources/GhosttyConfig.swift to load and parse standard Ghostty configuration files, maintaining full compatibility with existing Ghostty setups.
• Configuration files are searched in Ghostty-standard locations first (~/.config/ghostty/, ~/Library/Application Support/com.mitchellh.ghostty/), followed by cmux-specific Application Support directories.
• Themes are resolved using Ghostty’s light/dark syntax and loaded from an ordered search path that includes the app bundle, environment variables, and user data directories.
• Parsed values are cached in-process to avoid redundant file I/O, then propagated to the UI via direct struct access and UserDefaults for components like the sidebar and split dividers.

Frequently Asked Questions

Where does cmux look for Ghostty configuration files?

cmux searches the standard Ghostty configuration paths first: ~/.config/ghostty/config, ~/.config/ghostty/config.ghostty, ~/Library/Application Support/com.mitchellh.ghostty/config, and the .ghostty variant thereof. It then appends cmux-specific paths relative to the running bundle’s Application Support directory, allowing custom configs to ship with the application.

How do I specify different themes for light and dark mode in cmux?

Use Ghostty’s comma-separated syntax in your configuration file: theme = light:Solarized Light,dark:Solarized Dark. The resolveThemeName method in GhosttyConfig.swift (lines 93-115) automatically detects the current macOS appearance via currentColorSchemePreference and selects the appropriate theme variant.

Can I use custom Ghostty themes with cmux?

Yes. Place your custom theme folder (containing a colors file) in ~/Library/Application Support/com.mitchellh.ghostty/themes/ or any directory listed in themeSearchPaths. Reference the theme by name in your config file (e.g., theme = my-custom-theme), and cmux will discover and load it during startup, merging its color definitions with your other configuration settings.

Does cmux cache Ghostty configuration between terminal sessions?

Yes. The GhosttyConfig.load() method checks an in-process cache via cachedLoad (lines 83-87) before hitting the disk. This cache is keyed by the current color scheme preference, ensuring that subsequent terminal creations within the same app lifecycle reuse the parsed configuration without re-reading files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}