command-center/omp-docs/tools/ghostty/configuration.md

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.	terminal ghostty configuration reference	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.