# cmux Configuration Native macOS terminal built on [[Ghostty]]'s Metal rendering engine, adding workspace vertical tabs, split panes, notification rings, and a socket API on top of Ghostty. Runs with ==Catppuccin Mocha== to match [[Tmux Configuration|tmux]] and [[Neovim Configuration|Neovim]]. Config file: `~/.config/ghostty/config` (same file as Ghostty — cmux reads it directly) > [!info] What is cmux? > cmux ([cmux.dev](https://www.cmux.dev)) is a native macOS terminal multiplexer built on top of Ghostty's rendering engine. It adds vertical workspace tabs, split panes, notification rings, a socket API for external automation, and integrations with Claude Code, Codex, Gemini CLI, and other CLI AI tools. Because it uses Ghostty's renderer, every Ghostty setting (font, theme, split opacity, titlebar style) applies directly to cmux — there is no separate cmux config file. > [!note] Config directory > cmux has **no** `~/.cmux/` directory. That path belonged to a different, older tool with the same name. cmux.dev reads exclusively from `~/.config/ghostty/config` (and the macOS alternative `~/Library/Application Support/com.mitchellh.ghostty/config`). ## Config File Locations (in priority order) 1. `~/.config/ghostty/config` ← primary 2. `~/Library/Application Support/com.mitchellh.ghostty/config` ## Key Settings Settings in `~/.config/ghostty/config` that directly affect cmux behavior: | Setting | Value | Why | |---------|-------|-----| | `unfocused-split-opacity` | `0.85` | Dims inactive splits to show focus without losing readability | | `split-divider-color` | `#585b70` | Catppuccin Mocha "surface2" — subtle, themed divider | | `font-feature = calt` | enabled | JetBrains Mono programming ligatures (`!=`, `=>`, `>=`) | | `font-feature = liga` | enabled | Standard ligature support | | `font-thicken` | `true` | Better rendering on Retina displays | | `macos-titlebar-style` | `hidden` | cmux workspace tabs replace macOS titlebar, reclaims 28px | | `window-padding-balance` | `true` | Centers content with asymmetric padding | | `window-padding-color` | `extend` | Extends background into padding area | | `link-url` | `true` | Clickable URLs in terminal output | | `theme` | `Catppuccin Mocha` | Unified theme across all tools | ## Workspace Hierarchy cmux organizes the screen into a layered hierarchy: | Level | Description | |-------|-------------| | **Window** | The top-level macOS window | | **Workspace** | Named tab in the vertical sidebar (e.g., "work", "notes") | | **Pane** | A split within a workspace | | **Surface** | A single terminal surface (Ghostty's rendering unit) | Workspaces appear as vertical tabs on the left sidebar. Switching workspaces is instant. ## Key Bindings > [!tip] Reference > Check cmux's in-app help or [cmux.dev/docs](https://www.cmux.dev/docs) for the full, up-to-date keybinding list — these may vary across versions. ### Surfaces & Splits | Keys | Action | |------|--------| | `Cmd+D` | Split right | | `Cmd+Shift+D` | Split down | | `Cmd+]` / `Cmd+[` | Focus next / previous split | | `Cmd+Shift+Enter` | Toggle fullscreen | ### App Settings | Keys | Action | |------|--------| | `Cmd+,` | Open cmux settings | ## Integration with tmux cmux and tmux are complementary, not competing: | Responsibility | cmux | tmux | |----------------|------|------| | Workspace tabs (sidebar) | ✓ | — | | Notification rings | ✓ | — | | AI tool integrations | ✓ | — | | Session persistence | — | ✓ resurrect/continuum | | vim-tmux-navigator | — | ✓ | | Plugin ecosystem | — | ✓ TPM | **Workflow**: Start tmux inside a cmux workspace. cmux manages which project you are looking at; tmux manages windows and panes within each project and persists them across reboots. ### Required tmux config ```tmux # Allow OSC sequences (notifications, clipboard) to pass through to cmux/Ghostty set -g allow-passthrough on ``` ## Shell Helpers `~/.zsh/aliases/cmux.zsh` provides detection and notification utilities: ```zsh # Detect if running inside cmux is_cmux() # checks TERM_PROGRAM=ghostty + CMUX_WORKSPACE_ID # Run and notify on completion (terminal-notifier → bell fallback) notify-after make build notify-after go test -race ./... # Aliases na # notify-after nab # notify-after go build ./... nat # notify-after go test -race ./... ``` > [!note] Notification CLI > cmux.dev's notification API (socket API / OSC sequences) is not yet fully documented. The shell helper currently uses `terminal-notifier` as a fallback. Update `cmux.zsh` once the cmux.dev notification interface is confirmed. ## Theme Consistency ==Catppuccin Mocha== is configured across all tools: | Tool | Config Location | Setting | |------|----------------|---------| | **cmux / [[Ghostty Configuration\|Ghostty]]** | `~/.config/ghostty/config` | `theme = Catppuccin Mocha` | | **[[Tmux Configuration\|tmux]]** | `~/.tmux.conf` | `@catppuccin_flavor 'mocha'` | | **[[Neovim Configuration\|Neovim]]** | `~/.config/nvim/init.lua` | `flavour = 'mocha'` | ## Verification ```bash # Validate the shared Ghostty/cmux config ghostty +validate-config # Confirm no ~/.cmux/ directory exists (old tool — should be absent) ls ~/.cmux 2>&1 # should print: ls: cannot access ... # Check OSC passthrough is set in tmux grep 'allow-passthrough' ~/.tmux.conf # Verify font ligatures are enabled grep 'font-feature' ~/.config/ghostty/config ``` ## Decisions 1. **Shared config with Ghostty**: cmux reads `~/.config/ghostty/config` directly — no duplication. 2. **cmux + tmux coexistence**: cmux handles workspace tabs and notifications; tmux handles session persistence and vim-navigator. 3. **Hidden titlebar**: `macos-titlebar-style = hidden` reclaims 28px — cmux's sidebar replaces the native titlebar. 4. **Split opacity 0.85**: Dim enough to show focus, readable enough in unfocused splits. 5. **No `~/.cmux/` tracking**: That directory belonged to a different older tool. cmux.dev has no config directory.