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.
10 KiB
type, title, description, tags, verified
| type | title | description | tags | verified | ||||
|---|---|---|---|---|---|---|---|---|
| reference | Ghostty Configuration Options — Complete Reference | Every configuration option for Ghostty, organized by category with types, defaults, and usage examples. |
|
2026-08-28 |
Ghostty Configuration Reference
Complete option catalog for Ghostty. See Overview for setup and quick-start.
Font Configuration
font-family
Type: String (repeatable)
Primary font family with fallback support.
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.
font-feature = -calt # disable programming ligatures
font-feature = -liga # disable standard ligatures
font-size
Type: Number (can be non-integer, in points)
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).
font-variation = wght=700
font-variation = wdth=100
font-codepoint-map
Type: String (repeatable)
Force Unicode codepoints to map to a specific font.
font-codepoint-map = U+2500-U+257F=JetBrains Mono
clipboard-codepoint-map
Type: String (repeatable)
Map codepoints to replacement values when copying to clipboard.
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)
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
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)
keybind = foo/ctrl+a=new_window
keybind = foo/ # define and clear table
Key Remap
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 for CLI actions and quick-start.
- The AGENTS.md Format governs how agent behavior contracts reference this configuration.