Settings reference
Every setting in vmuxMac, organized by tab.
Opening Settings
Press Cmd+, or run Open Settings from the command palette. The macOS Settings window opens with four tabs: General, Appearance, CRT, and Mac.
Every change applies immediately and is saved automatically. There is no Apply or Save button. Settings live in defaults (specifically the keys vmux_terminal_settings and vmux_mac_terminal_preferences) and survive across launches.
General tab
The General tab covers cross-platform terminal settings shared with the rest of the vmux family.
Input
| Setting | Type | Description | Default |
|---|---|---|---|
| Option as Meta Key | Toggle | Send the Option key as Meta/Alt for vim, emacs, and similar tools. | On |
| Send COLORTERM | Toggle | Set COLORTERM=truecolor so programs use 24-bit color. | On |
| Mouse Reporting (Primary Buffer) | Toggle | Forward mouse events to programs on the primary screen buffer. Disable to use the mouse only for selection. | On |
While the Mac terminal renders through libghostty, the engine reads its own input semantics from your Ghostty config. The toggles above are stored but their effect is paused on Mac. They will start applying when the Metal pipeline returns. The General tab is greyed out to make this state explicit.
Cursor
| Setting | Type | Description | Default |
|---|---|---|---|
| Shape | Picker | Block, Hollow Block, Underline, or Bar. | Block |
| Blink | Toggle | Animate the cursor with a blinking effect. | On |
These are stored and shared with vmux on visionOS. The visible cursor on Mac today is drawn by libghostty.
Appearance tab
The Appearance tab covers theme, font, and background. Like the General tab, settings are stored and shared with the rest of the vmux family even though their visible effect on Mac is currently paused.
Theme
| Setting | Type | Description | Default |
|---|---|---|---|
| Theme | Picker | Color scheme. The picker shows every theme in your library. | Ghostty |
See Themes and fonts for browsing, importing VSCode themes, and the bundled selection.
Font
| Setting | Type | Description | Default |
|---|---|---|---|
| Size | Slider | Text size in points (8 – 32). | 14 pt |
| Weight | Picker | Regular or Bold. | Regular |
See Fonts for installing Nerd Fonts and the discovery rules.
Background
| Setting | Type | Description | Default |
|---|---|---|---|
| Opacity | Slider | Background opacity (0% – 100%). | 100% |
The opacity slider is honored by the command palette panel and managed vmux sessions. The local-shell terminal background is opaque while the libghostty pipeline is in use.
CRT tab
The CRT tab is currently a placeholder.
| Setting | Type | Description | Default |
|---|---|---|---|
| Enable CRT Effect | Toggle (disabled) | Master toggle for CRT post-processing. | Off |
The tab also displays a note explaining that CRT is paused on Mac while the terminal uses libghostty native drawing. Your CRT slider settings (scanlines, vignette, bloom, etc.) are stored and remain in sync with vmux on visionOS, but no Mac UI exposes them today.
See CRT effects for the full list of values that will apply when the pipeline returns.
Mac tab
The Mac tab is the place to look for everything specific to the macOS app. These settings are active today.
Window
| Setting | Type | Description | Default |
|---|---|---|---|
| Hidden Title Bar | Toggle | Hide the standard macOS title bar; traffic-light controls float over the terminal. | On |
| Padding | Slider | Pixel padding around the terminal content (0 – 80 px). | 20 px |
Hidden Title Bar gives a more cinematic look that matches modern terminal apps; turn it off for the standard Mac chrome with a window title across the top. Padding controls how far the terminal content is inset from the window edges; set it to zero for an edge-to-edge terminal.
Input
| Setting | Type | Description | Default |
|---|---|---|---|
| Focus Follows Mouse | Toggle | Switch keyboard focus to whichever window your pointer is over. | On |
| Bracketed Paste | Toggle | Wrap pasted text in bracketed-paste sequences so the remote shell can detect it. | On |
Focus Follows Mouse matches Ghostty's default behavior — you can have several windows visible and type into whichever you point at. Bracketed paste protects the remote shell from running arbitrary commands when you paste; almost every modern shell supports it, but you can disable it if you have a tool that mishandles the sequences.
Cursor
| Setting | Type | Description | Default |
|---|---|---|---|
| Opacity | Slider | Cursor opacity (5% – 100%). | 70% |
Lowering cursor opacity makes the cursor a translucent overlay so it does not visually replace text it sits on. This is unique to vmuxMac among the vmux family.
Migration
| Setting | Type | Description |
|---|---|---|
| Import Ghostty Config | Button | Reads your Ghostty config and applies recognized keys. |
After running, the section shows how many settings were applied. Run it again any time you change your Ghostty config — it is idempotent. See Themes and fonts for the recognized-key list.
Persistence
Settings are saved automatically. They persist across app launches. Saves are batched: changing several settings rapidly results in one disk write a moment later, not one write per click.
| Stored at | Location |
|---|---|
| App preferences | ~/Library/Preferences/app.vmux.mac.plist (via defaults) |
| Themes (imported) | ~/Library/Application Support/vmuxMac/themes/ |
| Saved hosts | App-managed, encrypted with the Keychain |
| Passwords | macOS Keychain |
| SSH keys (imported) | App-managed, encrypted with the Keychain |
Passwords are never written to disk in plain text. They live in the Keychain and are pulled out only when needed for an active connection. Secure Enclave keys never leave the chip.
Reset
There is no global "reset to defaults" button. To start fresh:
- Quit vmuxMac.
- Run
defaults delete app.vmux.macin a normal Terminal window. - Relaunch vmuxMac.
This clears every preference. Saved hosts and imported themes are not deleted by defaults delete — to remove those, also delete ~/Library/Application Support/vmuxMac/.
Missing or moved settings
A few settings present in vmux on visionOS are intentionally absent from vmuxMac because they only make sense in a spatial environment:
- VKeyboard — UI scale, pitch, floor lift, key opacity, cursor halo and ring, swipe trail, reachability dimming.
- Glass background and glass style — vmuxMac is opaque.
- Battlestation Mode and Pane Tabs / Multi-Window — Mac uses native windows and tabs.
- Optic ID lock — vmuxMac uses Touch ID where available.
- Pane border opacity — Mac windows do not draw vmux pane borders.
If you syncronize a profile between vmuxMac and vmux on visionOS, these settings still travel; they are simply not surfaced in the Mac UI.
Where to go next
- Themes and fonts — appearance deep dive.
- Command palette — change settings without opening this window.
- Shell (vsh) — change settings from the keyboard.
- Troubleshooting — what to do when settings do not seem to apply.