# How cmux Integrates with Ghostty Configuration Files and Themes

> Discover how cmux integrates seamlessly with Ghostty configuration files and themes. Learn how cmux uses the GhosttyConfig Swift struct to load settings and style its UI.

- Repository: [manaflow-ai/cmux](https://github.com/manaflow-ai/cmux)
- Tags: how-to-guide
- Published: 2026-03-29

---

**cmux embeds the Ghostty terminal engine and consumes the same configuration file format, using the `GhosttyConfig` struct in [`Sources/GhosttyConfig.swift`](https://github.com/manaflow-ai/cmux/blob/main/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:

```swift
let config = GhosttyConfig.load()

```

According to the source code in [`AppDelegate.swift`](https://github.com/manaflow-ai/cmux/blob/main/AppDelegate.swift) at line 6417 and [`TerminalView.swift`](https://github.com/manaflow-ai/cmux/blob/main/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`](https://github.com/manaflow-ai/cmux/blob/main/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:

```swift
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`](https://github.com/manaflow-ai/cmux/blob/main/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`](https://github.com/manaflow-ai/cmux/blob/main/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`](https://github.com/manaflow-ai/cmux/blob/main/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`](https://github.com/manaflow-ai/cmux/blob/main/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.