Ghostty terminals
Ghostex embeds Ghostty natively for agent CLI sessions. Terminals are first-class AppKit surfaces with shared Ghostty configuration, reliable copy/paste, and the same pane layout model as browsers and T3 Code.
GhosttyNative terminalszmx
What it is
Ghostex uses embedded Ghostty (terminalEngine: ghostty-native) instead of xterm.js or a web-based terminal. Each agent or shell session renders in a native Ghostty SurfaceView inside the macOS workspace.
Ghostty ships with bundled themes, terminfo, and runtime resources in the app bundle. Ghostex strips inherited color-disabling environment keys at the native boundary so agent CLIs keep ANSI color output.
How it works
Terminal lifecycle in Ghostex:
- New sessions receive a Ghostex environment overlay (agent metadata, prompt editor, persistence provider) before Ghostty attaches.
- zmx-backed sessions ask gxserver for render metadata before Swift creates the Ghostty surface.
- Pane layout sizes step to whole Ghostty character cells, including configured terminal padding.
- Sleep keeps the renderer as a view owner; wake recreates or reattaches the surface and may replay resume commands.
- Remote session clicks can open a local Ghostty terminal that SSH-attaches with the stable ghostex attach contract.
Terminal settings in Ghostex write documented Ghostty config keys to the shared Ghostty config file. External Ghostty windows read the same file; embedded terminals reload about three seconds after you stop changing controls.
Default terminal profile
New Ghostex installs seed this baseline (overridable in Settings):
| Option | What it does |
|---|---|
Theme | GitHub Dark |
Font | JetBrains Mono 13pt, font-variation wght=300 |
Cursor | Bar cursor with blink enabled |
Line height | 1.2 (20% cell height expansion in Ghostty config) |
Scrollback | 15 MB per surface |
Copy on select | Off |
Mouse scroll | Precision 1, discrete 1 |
Scrollbar | System |
Paste previewable images | On (app-owned, not a Ghostty key) |
Settings sections
Settings → Terminal (typography & theme):
| Option | What it does |
|---|---|
ghosttySettingsActions | Apply recommended settings, open config file, open Ghostty docs, reset defaults. |
terminalGhosttyTheme | Bundled theme or Use existing Ghostty config. |
terminalFontFamily | Ghostty font-family string; blank preserves existing config. |
terminalFontSize | 8–32 pt (0.5 step). |
terminalFontWeight | 100–900 (maps to font-variation wght=…). |
terminalLineHeight | 0.8–2.0 row height multiplier. |
terminalLetterSpacing | Glyph spacing via adjust-cell-width. |
terminalCursorStyle | Line (bar), Block, or Underline. |
terminalCursorStyleBlink | Blink the terminal cursor. |
sessionPersistenceProvider | Off or zmx (recommended) for new terminal/agent sessions. |
showSessionIdInTerminalPanes | Show provider session id in the top-right of terminal panes when persistence is enabled. |
promptEditorBackend | Ctrl+G prompt editor backend (see Rich prompt editor docs). |
Settings → Terminal Behavior:
| Option | What it does |
|---|---|
terminalScrollbackLimitMb | 1–200 MB scrollback memory per surface. |
terminalCopyOnSelect | Off, Selection clipboard, or System and selection clipboard. |
terminalConfirmCloseSurface | Smart confirmation, Always confirm, or Do not confirm. |
terminalClipboardTrimTrailingSpaces | Trim trailing whitespace on copy (default on). |
terminalClipboardPasteProtection | Ask before pasting text Ghostty considers unsafe (default on). |
terminalPastePreviewableImages | Paste images as previewable Markdown links (default on). |
terminalMouseHideWhileTyping | Hide pointer while typing. |
terminalScrollbar | System or Never. |
Settings → Terminal Scrolling:
| Option | What it does |
|---|---|
terminalMouseScrollMultiplierPrecision | Trackpads / hi-res wheels (Ghostty default 1). |
terminalMouseScrollMultiplierDiscrete | Notched wheels (Ghostty default 3; Ghostex default 1). |
terminalScrollToBottomWhenTyping | Keep prompt visible while typing (default on). |
Copy, paste, and images
| Option | What it does |
|---|---|
Cmd+C | Uses Ghostty's copy action when text is selected so clipboard matches the terminal selection. |
Middle click | Disabled for paste in embedded Ghostty terminals. |
Paste protection | Ghostty prompts before pasting potentially unsafe text when enabled. |
Cmd+V / Ctrl+V images | When Paste previewable images is on, bitmap clipboard paste stores durable file references instead of dumping base64 into the shell. |
Ctrl+V | Passes through to terminal programs unless the clipboard currently contains an image (then Ghostex intercepts for image paste). |
Keyboard shortcuts
Ghostex app shortcuts for terminal workflows (defaults, rebindable in Settings → Hotkeys):
| Option | What it does |
|---|---|
Cmd+T | Create Session — new terminal tab after the focused tab. |
Cmd+D | Split focused pane horizontally. |
Cmd+Shift+D | Split focused pane vertically. |
Cmd+R | Rename active session. |
Ctrl+Shift+R | Reload focused session. |
Ctrl+Shift+L | Rotate panes clockwise. |
F12 | Open Commands panel. |
Cmd+B | Collapse/expand sidebar. |
Ghostty-native shortcuts while terminal focus is inside the embed:
- Cmd+Shift+, — reload Ghostty config in external Ghostty windows.
- Option acts as Alt for terminal keybindings when macos-option-as-alt is enabled.
- Visible native scrollbars with square scroll-to-top/bottom overlay buttons.
Sleep and persistence
Terminal sessions interact with Ghostex sleep and persistence policies:
- Session Persistence provider zmx (recommended) keeps new terminal/agent sessions restorable across restarts and remote attach.
- Turning persistence Off shows a warning that Android/iOS attach can have issues.
- Click to wake sleeping panes (Settings → Workspace): selecting a sleeping tab shows a black placeholder until you click the pane body.
- Agent Auto Sleep never sleeps the focused agent session; terminal candidates come from gxserver presentation when active.
- Delayed Send timers block auto-sleep for affected terminal sessions.
CLI commands
| Option | What it does |
|---|---|
ghostex create-session | Create a shell terminal session. |
ghostex create-agent <id> | Launch a configured agent in a new terminal. |
ghostex send-text / send-enter / send-key | Inject input into the selected Ghostty surface. |
ghostex read-text | Read terminal screen buffer or visible viewport. |
ghostex sleep-session / reload-session | Sleep or reload a terminal session. |
ghostex attach | Attach to a remote or persisted session (stable --session-id / --project-id contract). |
gx create-agent codex
gx send-text codex "summarize the last error"
gx read-text --index 0 --visible
gx sleep-session g-0614-120000 trueTips
- Use zmx persistence when you want SSH or mobile attach to resume the same named sessions Ghostex created.
- Enable show session id in terminal panes while debugging zmx attach from another machine.
- If scroll feels too fast or slow, tune precision and discrete multipliers separately — Ghostty treats them as different device classes.
- Apply recommended Ghostty settings after major upgrades to pick up the GitHub Dark + JetBrains Mono baseline.
- Enable Debugging Mode temporarily when diagnosing focus steals — native activation and pane-tab geometry logs help trace terminal focus issues.