# How to Configure cmux to Read an Existing Ghostty Configuration

> Effortlessly configure cmux to read your existing Ghostty configuration from standard locations. cmux auto-detects settings for seamless integration without manual steps.

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

---

**cmux automatically detects and reads existing Ghostty configuration files from standard locations including `~/.config/ghostty/` and `~/Library/Application Support/com.mitchellh.ghostty/` without requiring command-line flags or manual imports.**

cmux re-uses the Ghostty configuration system to ensure backward compatibility with your existing terminal setup. When you configure cmux to read existing Ghostty config files, it searches multiple standard paths, applies themes and fonts instantly, and even reloads live when files change.

## Where cmux Searches for Ghostty Configuration

The loader prioritizes configuration files in the following order, checking each location sequentially until it finds a valid config:

- `~/.config/ghostty/config`
- `~/.config/ghostty/config.ghostty`
- `~/Library/Application Support/com.mitchellh.ghostty/config`
- `~/Library/Application Support/com.mitchellh.ghostty/config.ghostty`
- `<Application-Support>/<cmux-bundle-id>/config`
- `<Application-Support>/<cmux-bundle-id>/config.ghostty`

This search list is constructed inside `loadFromDisk(preferredColorScheme:)` in [`Sources/GhosttyConfig.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/GhosttyConfig.swift). The algorithm merges classic Ghostty directories with **cmux-specific support paths** returned by `cmuxConfigPaths()`, ensuring that standard Ghostty installations and cmux-specific overrides coexist.

## The Configuration Loading Pipeline

Understanding how cmux ingests these files helps troubleshoot issues and optimize startup performance.

### Entry Point and Caching

The loading process begins with `GhosttyConfig.load()` in [`Sources/GhosttyConfig.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/GhosttyConfig.swift). This method resolves the current macOS appearance (light or dark), checks an in-memory cache to avoid redundant disk operations, and delegates the heavy lifting to `loadFromDisk(preferredColorScheme:)`.

### Building the Search List

The `loadFromDisk` method constructs a `configPaths` array that combines standard Ghostty directories with cmux-specific locations. It iterates through these paths, calling `readConfigFile(at:)` to parse each discovered file line-by-line into the `GhosttyConfig` struct. The parsing logic handles key-value pairs, theme declarations, and font specifications according to Ghostty's configuration grammar.

### cmux-Specific Override Directories

The `cmuxConfigPaths()` function (lines 98-141 in [`Sources/GhosttyConfig.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/GhosttyConfig.swift)) looks specifically in the macOS Application Support folder for the cmux bundle identifier `com.cmuxterm.app`. If you are running a debug build with a different bundle ID, it intelligently falls back to release paths so that a single configuration works across development and production environments.

### Parsing and UI Application

After parsing, `Workspace.applyGhosttyChrome(from:reason:)` in [`Sources/Workspace.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/Workspace.swift) (line 5663) consumes the loaded `GhosttyConfig`. This method updates the UI surface—including theme colors, font families, sidebar styling, and scrollback limits—ensuring every terminal window reflects the Ghostty settings immediately.

## Implementing Your Configuration

### Using Existing Ghostty Files

If you already use Ghostty, no migration is necessary. Place your `config` file in any of the standard locations listed above, and cmux will read it automatically on the next launch. The `theme=` line is resolved via `GhosttyConfig.resolveThemeName`, which searches Ghostty’s theme directories (system, XDG, and bundle resources) without additional configuration.

### Creating cmux-Only Overrides

To override settings exclusively for cmux while preserving Ghostty defaults, create a config file in the cmux Application Support directory:

```bash

# Create the directory if it doesn't exist

mkdir -p "$HOME/Library/Application Support/com.cmuxterm.app"

# Write cmux-specific settings

cat > "$HOME/Library/Application Support/com.cmuxterm.app/config" <<EOF
font-family = "Fira Code"
font-size   = 14
theme       = "Dracula"
EOF

```

When cmux launches, it reads this file after the standard Ghostty locations, allowing these values to override any previous settings.

## Live Reload and File Watching

cmux monitors configuration files for changes without requiring a restart. `AppDelegate.installGhosttyConfigObserver()` in [`Sources/AppDelegate.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/AppDelegate.swift) (line 8923) installs a file-system watcher on all discovered config paths. When a modification is detected, it triggers `AppDelegate.refreshTerminalSurfacesAfterGhosttyConfigReload(source:)`, which reapplies the configuration to all open terminal surfaces in real time.

## Practical Configuration Examples

### Loading Configuration Programmatically

Access the current configuration in Swift to inspect loaded values:

```swift
import cmux

let config = GhosttyConfig.load()
print("Font:", config.fontFamily, config.fontSize)
print("Theme:", config.theme ?? "system")

```

### Forcing a Specific Color Scheme

Override the automatic appearance detection by specifying a preferred color scheme:

```swift
let config = GhosttyConfig.load(preferredColorScheme: .dark)

```

### Triggering Manual Reloads

Programmatically refresh the terminal UI after external configuration changes:

```swift
AppDelegate.shared?.refreshTerminalSurfacesAfterGhosttyConfigReload(source: "script-trigger")

```

## Summary

- **Zero configuration required**: cmux automatically reads existing Ghostty configs from `~/.config/ghostty/` and `~/Library/Application Support/com.mitchellh.ghostty/`.
- **Override support**: Drop a config file in `$HOME/Library/Application Support/com.cmuxterm.app/` to apply cmux-only settings.
- **Live reloading**: File system observers in [`AppDelegate.swift`](https://github.com/manaflow-ai/cmux/blob/main/AppDelegate.swift) refresh the UI instantly when config files change.
- **Debug compatibility**: The `cmuxConfigPaths()` function handles both release and debug bundle identifiers seamlessly.

## Frequently Asked Questions

### Does cmux require a separate configuration file from Ghostty?

No. cmux is designed to read existing Ghostty configuration files directly. If you have a Ghostty config in `~/.config/ghostty/` or `~/Library/Application Support/com.mitchellh.ghostty/`, cmux will discover and apply it automatically without requiring a separate cmux-specific file.

### Can I use different themes for cmux and Ghostty simultaneously?

Yes. Create a cmux-specific config file at `~/Library/Application Support/com.cmuxterm.app/config` containing only the theme override. According to the source code in [`GhosttyConfig.swift`](https://github.com/manaflow-ai/cmux/blob/main/GhosttyConfig.swift), cmux-specific paths are checked after standard Ghostty locations, so values in the cmux directory take precedence.

### How do I force cmux to reload the configuration without restarting the application?

The application monitors config files automatically via `installGhosttyConfigObserver()`. Simply save your changes to any watched config file, and cmux will trigger `refreshTerminalSurfacesAfterGhosttyConfigReload(source:)` to update all terminal surfaces immediately.

### Where should I place my config file if I use both debug and release builds of cmux?

Place your config in `~/Library/Application Support/com.cmuxterm.app/` for release builds. The `cmuxConfigPaths()` function in [`Sources/GhosttyConfig.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/GhosttyConfig.swift) (lines 98-141) automatically detects debug bundle identifiers and falls back to release paths, ensuring a single configuration works across both build types.