How to Configure cmux to Read an Existing Ghostty Configuration

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. 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. 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) 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 (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:

# 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 (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:

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:

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

Triggering Manual Reloads

Programmatically refresh the terminal UI after external configuration changes:

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 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, 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 (lines 98-141) automatically detects debug bundle identifiers and falls back to release paths, ensuring a single configuration works across both build types.

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