Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
493 lines
10 KiB
Markdown
493 lines
10 KiB
Markdown
---
|
||
type: reference
|
||
title: Ghostty Configuration Options — Complete Reference
|
||
description: Every configuration option for Ghostty, organized by category with types, defaults, and usage examples.
|
||
tags:
|
||
- terminal
|
||
- ghostty
|
||
- configuration
|
||
- reference
|
||
verified: 2026-08-28
|
||
---
|
||
|
||
# Ghostty Configuration Reference
|
||
|
||
Complete option catalog for [Ghostty](https://ghostty.org). See [Overview](index.md) for setup and quick-start.
|
||
|
||
---
|
||
|
||
## Font Configuration
|
||
|
||
### `font-family`
|
||
|
||
**Type**: String (repeatable)
|
||
|
||
Primary font family with fallback support.
|
||
|
||
```ini
|
||
font-family = "JetBrains Mono"
|
||
font-family = "Noto Sans Mono" # fallback
|
||
```
|
||
|
||
Styles (bold, italic, bold-italic) are automatically found. Use `ghostty +list-fonts` to see available fonts.
|
||
|
||
### `font-style`, `font-style-bold`, `font-style-italic`, `font-style-bold-italic`
|
||
|
||
**Type**: String or `false`
|
||
|
||
A named font style from the font's own style string, for example "Heavy" or "Semibold". Set to `false` to completely disable a style.
|
||
|
||
### `font-synthetic-style`
|
||
|
||
**Type**: String (comma-separated)
|
||
|
||
Control whether Ghostty synthesizes missing styles. Values: `true`, `false`, `bold,italic,bold-italic`, `no-bold,no-italic`.
|
||
|
||
### `font-feature`
|
||
|
||
**Type**: String (repeatable, comma-separated)
|
||
|
||
OpenType font features. Enable: `feat`, `+feat`, `feat on`, `feat=1`. Disable: `-feat`, `feat off`, `feat=0`.
|
||
|
||
```ini
|
||
font-feature = -calt # disable programming ligatures
|
||
font-feature = -liga # disable standard ligatures
|
||
```
|
||
|
||
### `font-size`
|
||
|
||
**Type**: Number (can be non-integer, in points)
|
||
|
||
```ini
|
||
font-size = 12
|
||
font-size = 13.5 # 27px on a 2x DPI display
|
||
```
|
||
|
||
### `font-variation`
|
||
|
||
**Type**: String in `id=value` format (repeatable)
|
||
|
||
Variable font axis values (4-character IDs).
|
||
|
||
```ini
|
||
font-variation = wght=700
|
||
font-variation = wdth=100
|
||
```
|
||
|
||
### `font-codepoint-map`
|
||
|
||
**Type**: String (repeatable)
|
||
|
||
Force Unicode codepoints to map to a specific font.
|
||
|
||
```ini
|
||
font-codepoint-map = U+2500-U+257F=JetBrains Mono
|
||
```
|
||
|
||
### `clipboard-codepoint-map`
|
||
|
||
**Type**: String (repeatable)
|
||
|
||
Map codepoints to replacement values when copying to clipboard.
|
||
|
||
```ini
|
||
clipboard-codepoint-map = U+2500=U+002D # box drawing → hyphen
|
||
clipboard-codepoint-map = U+03A3=SUM # Greek sigma → "SUM"
|
||
```
|
||
|
||
### `grapheme-width-method`
|
||
|
||
**Type**: String
|
||
|
||
Width calculation method: `unicode` (default, correct but can cause cursor-desync) or `legacy` (wcswidth, maximizes compatibility).
|
||
|
||
---
|
||
|
||
## Alpha Blending & Rendering
|
||
|
||
### `alpha-blending`
|
||
|
||
**Type**: String
|
||
|
||
Color space for alpha blending (available since 1.1.0): `native` (OS-native, macOS default), `linear` (eliminates darkening artifacts), `linear-corrected` (Linux default).
|
||
|
||
---
|
||
|
||
## Cell Adjustments
|
||
|
||
All `adjust-*` options accept integers (1, -1) or percentages (20%, -15%).
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `adjust-cell-width` | Cell width adjustment |
|
||
| `adjust-cell-height` | Cell height (also centers font vertically, adjusts Powerline glyphs) |
|
||
| `adjust-font-baseline` | Baseline position |
|
||
| `adjust-underline-position` | Underline position |
|
||
| `adjust-underline-thickness` | Underline thickness |
|
||
| `adjust-strikethrough-position` | Strikethrough position |
|
||
| `adjust-strikethrough-thickness` | Strikethrough thickness |
|
||
| `adjust-overline-position` | Overline position |
|
||
| `adjust-overline-thickness` | Overline thickness |
|
||
| `adjust-cursor-thickness` | Bar/rect cursor thickness |
|
||
| `adjust-cursor-height` | Cursor height |
|
||
| `adjust-box-thickness` | Box drawing character thickness |
|
||
| `adjust-icon-height` | Nerd font icon height (available since 1.2.0) |
|
||
|
||
**Warning**: Invalid values, for example -100%, can make the terminal unusable.
|
||
|
||
---
|
||
|
||
## Theme & Colors
|
||
|
||
### `theme`
|
||
|
||
**Type**: String
|
||
|
||
Theme name, absolute path, or light/dark pair: `light:Rose Pine Dawn,dark:Rose Pine`.
|
||
|
||
### `background` / `foreground`
|
||
|
||
**Type**: Color (`#RRGGBB`, `RRGGBB`, or named X11 color)
|
||
|
||
### `palette`
|
||
|
||
**Type**: `N=COLOR` (repeatable, N = 0–255)
|
||
|
||
```ini
|
||
palette = 0=#1d1f21
|
||
palette = 0x00=#1d1f21
|
||
palette-generate = true
|
||
```
|
||
|
||
Only set 0-15 for most themes; 16-255 auto-generated if `palette-generate` is enabled.
|
||
|
||
### `bold-color`
|
||
|
||
**Type**: Color or `bright` (available since 1.2.0)
|
||
|
||
Replaces deprecated `bold-is-bright`.
|
||
|
||
### `minimum-contrast`
|
||
|
||
**Type**: Number (1-21)
|
||
|
||
Minimum contrast ratio (WCAG 2.0). Value of 3+ = avoid hard-to-read text.
|
||
|
||
---
|
||
|
||
## Appearance
|
||
|
||
### `background-image`
|
||
|
||
**Type**: Path (PNG or JPEG, available since 1.2.0)
|
||
|
||
Per-terminal background image. **Warning**: Currently duplicated in VRAM per-terminal.
|
||
|
||
### `background-opacity`
|
||
|
||
**Type**: Number (0-1)
|
||
|
||
Window transparency. On macOS, disabled in native fullscreen.
|
||
|
||
### `background-blur`
|
||
|
||
**Type**: Number, `true`, `false`, or macOS special values
|
||
|
||
Blur background when opacity < 1. macOS special: `macos-glass-regular`, `macos-glass-clear` (macOS 26.0+).
|
||
|
||
---
|
||
|
||
## Selection
|
||
|
||
### `copy-on-select`
|
||
|
||
**Type**: Boolean or `clipboard`
|
||
|
||
Automatically copy selected text. `clipboard` copies to both selection and system clipboard.
|
||
|
||
### `selection-clear-on-typing`
|
||
|
||
**Type**: Boolean (available since 1.2.0)
|
||
|
||
Clear selection when typing. Default: `true`.
|
||
|
||
---
|
||
|
||
## Cursor
|
||
|
||
### `cursor-style`
|
||
|
||
**Type**: String
|
||
|
||
`block`, `bar`, `underline`, `block_hollow`. Programs can override via DECSCUSR.
|
||
|
||
### `cursor-click-to-move`
|
||
|
||
**Type**: Boolean
|
||
|
||
Click to move cursor at prompts (requires shell integration). Default: `true`.
|
||
|
||
---
|
||
|
||
## Mouse
|
||
|
||
### `mouse-hide-while-typing`
|
||
|
||
**Type**: Boolean
|
||
|
||
Hide mouse when typing.
|
||
|
||
### `mouse-reporting`
|
||
|
||
**Type**: Boolean
|
||
|
||
Allow terminal applications to receive mouse events. Default: `true`. Toggle with `toggle_mouse_reporting` keybind.
|
||
|
||
---
|
||
|
||
## Scrolling
|
||
|
||
### `scroll-to-bottom`
|
||
|
||
**Type**: String (comma-separated)
|
||
|
||
When to auto-scroll: `keystroke` (default), `output`.
|
||
|
||
### `scrollback-limit`
|
||
|
||
**Type**: Integer (bytes)
|
||
|
||
Scrollback buffer size. Default: `10000000` (10 MB).
|
||
|
||
---
|
||
|
||
## Split Panes
|
||
|
||
### `unfocused-split-opacity`
|
||
|
||
**Type**: Number (0.15-1)
|
||
|
||
Opacity of unfocused split. Default: `0.7`. Minimum: `0.15`.
|
||
|
||
### `split-divider-color`
|
||
|
||
**Type**: Color (available since 1.1.0)
|
||
|
||
Color of split dividers.
|
||
|
||
---
|
||
|
||
## Shell Integration
|
||
|
||
### `shell-integration`
|
||
|
||
**Type**: String
|
||
|
||
`none`, `detect` (default), `bash`, `elvish`, `fish`, `nushell`, `zsh`. `detect` auto-detects by filename.
|
||
|
||
### `shell-integration-features`
|
||
|
||
**Type**: String (comma-separated)
|
||
|
||
Features: `cursor`, `sudo`, `title`, `ssh-env`, `ssh-terminfo`, `path`. Negate with `no-`.
|
||
|
||
---
|
||
|
||
## Environment & Command
|
||
|
||
### `command`
|
||
|
||
**Type**: String
|
||
|
||
Shell/command to run. Uses `/bin/sh -c` for argument expansion unless prefixed with `direct:` or `shell:`.
|
||
|
||
### `env`
|
||
|
||
**Type**: `KEY=VALUE` (repeatable, available since 1.2.0)
|
||
|
||
Extra environment variables. Set `env =` to reset all.
|
||
|
||
---
|
||
|
||
## Window Settings
|
||
|
||
### `maximize`
|
||
|
||
**Type**: Boolean (available since 1.1.0)
|
||
|
||
Start maximized. Default: `false`.
|
||
|
||
### `fullscreen`
|
||
|
||
**Type**: String
|
||
|
||
`false`, `true` (native), `non-native`, `non-native-visible-menu`, `non-native-padded-notch` (macOS only).
|
||
|
||
### `window-decoration`
|
||
|
||
**Type**: String or Boolean (available since 1.1.0)
|
||
|
||
`none`, `auto` (default), `client`, `server`. Booleans: `true` = `auto`, `false` = `none`.
|
||
|
||
### `window-padding-x` / `window-padding-y`
|
||
|
||
**Type**: Number or `X,Y`
|
||
|
||
Padding in points. Default: `2`.
|
||
|
||
---
|
||
|
||
## Clipboard
|
||
|
||
### `clipboard-read` / `clipboard-write`
|
||
|
||
**Type**: String
|
||
|
||
`ask`, `allow`, `deny`. Defaults: `ask` / `allow`.
|
||
|
||
### `clipboard-paste-protection`
|
||
|
||
**Type**: Boolean
|
||
|
||
Require confirmation before pasting potentially unsafe text. Default: `true`.
|
||
|
||
---
|
||
|
||
## Notifications & Bell
|
||
|
||
### `bell-features`
|
||
|
||
**Type**: String (comma-separated, available since 1.2.0)
|
||
|
||
Features: `system`, `audio`, `attention` (default), `title` (default), `border`. Negate with `no-`.
|
||
|
||
### `desktop-notifications`
|
||
|
||
**Type**: Boolean
|
||
|
||
Allow apps to show desktop notifications via escape sequences. Default: `true`.
|
||
|
||
---
|
||
|
||
## Custom Shaders
|
||
|
||
### `custom-shader`
|
||
|
||
**Type**: Path (repeatable)
|
||
|
||
GLSL shader file path. Compatible with Shadertoy. Receives uniforms: `iChannel0` (screen texture), `iResolution`, `iTime`, `iCursorColor`, `iPalette[256]`, and more.
|
||
|
||
### `custom-shader-animation`
|
||
|
||
**Type**: Boolean or `always`
|
||
|
||
Run animation loop even when unfocused: `always`.
|
||
|
||
---
|
||
|
||
## Keybindings
|
||
|
||
### Format
|
||
|
||
```ini
|
||
keybind = trigger=action
|
||
keybind = chain=action # chain with previous keybind
|
||
```
|
||
|
||
**Modifiers**: `shift`, `ctrl`/`control`, `alt`/`opt`/`option`, `super`/`cmd`/`command`
|
||
|
||
**Prefixes**: `all:`, `global:`, `unconsumed:`, `performable:`, `physical:`
|
||
|
||
### Key Tables (available since 1.3.0)
|
||
|
||
```ini
|
||
keybind = foo/ctrl+a=new_window
|
||
keybind = foo/ # define and clear table
|
||
```
|
||
|
||
### Key Remap
|
||
|
||
```ini
|
||
key-remap = ctrl=super
|
||
key-remap = left_control=right_alt
|
||
```
|
||
|
||
---
|
||
|
||
## VT/Compatibility
|
||
|
||
### `term`
|
||
|
||
**Type**: String
|
||
|
||
TERM environment variable. Default: `xterm-ghostty`.
|
||
|
||
### `async-backend`
|
||
|
||
**Type**: String (available since 1.2.0, Linux only)
|
||
|
||
`auto` (default), `epoll`, `io_uring`. macOS always uses `kqueue`.
|
||
|
||
---
|
||
|
||
## Miscellaneous
|
||
|
||
### `confirm-close-surface`
|
||
|
||
**Type**: Boolean or `always`
|
||
|
||
Confirm before closing surface. Default: `true`.
|
||
|
||
### `focus-follows-mouse`
|
||
|
||
**Type**: Boolean
|
||
|
||
Auto-focus split under mouse. Default: `false`.
|
||
|
||
### `right-click-action`
|
||
|
||
**Type**: String
|
||
|
||
`context-menu` (default), `paste`, `copy`, `copy-or-paste`, `ignore`.
|
||
|
||
---
|
||
|
||
## Appendix: Default Keybindings
|
||
|
||
| Keybind | Action |
|
||
|---------|--------|
|
||
| `ctrl+shift+,` | `reload_config` |
|
||
| `ctrl+,` | `open_config` |
|
||
| `copy` | `copy_to_clipboard:mixed` |
|
||
| `paste` | `paste_from_clipboard` |
|
||
| `ctrl+shift+c` | `copy_to_clipboard:mixed` |
|
||
| `ctrl+shift+v` | `paste_from_clipboard` |
|
||
| `ctrl+=` / `ctrl++` | `increase_font_size:1` |
|
||
| `ctrl+-` | `decrease_font_size:1` |
|
||
| `ctrl+0` | `reset_font_size` |
|
||
| `shift+PageUp` | `scroll_page_up` |
|
||
| `shift+PageDown` | `scroll_page_down` |
|
||
| `shift+Home` | `scroll_to_top` |
|
||
| `shift+End` | `scroll_to_bottom` |
|
||
| `ctrl+shift+Tab` | `previous_tab` |
|
||
| `ctrl+Tab` | `next_tab` |
|
||
| `ctrl+shift+n` | `new_window` |
|
||
| `ctrl+shift+w` | `close_tab:this` |
|
||
| `ctrl+shift+q` | `quit` |
|
||
| `ctrl+shift+t` | `new_tab` |
|
||
| `ctrl+shift+o` | `new_split:right` |
|
||
| `ctrl+shift+e` | `new_split:down` |
|
||
| `ctrl+shift+f` | `start_search` |
|
||
| `Escape` | `end_search` |
|
||
| `ctrl+shift+a` | `select_all` |
|
||
| `alt+1`-`alt+9` | `goto_tab:1`-`goto_tab:9` |
|
||
| `ctrl+Enter` | `toggle_fullscreen` |
|
||
| `ctrl+shift+P` | `toggle_command_palette` |
|
||
|
||
---
|
||
|
||
## Cross-References
|
||
|
||
- See [Overview](index.md) for CLI actions and quick-start.
|
||
- The [AGENTS.md Format](/core/agents-md-format.md) governs how agent behavior contracts reference this configuration.
|