Ghostty configuration, themes and terminal capabilities

Ghostty renders program output and forwards keyboard input. Tiling belongs to the compositor, persistent sessions to Zellij and command completion to the shell. Identify the responsible layer before changing settings.

The examples were checked with Ghostty 1.3.1. Window options vary by platform; consult the installed version's reference when an option is unknown.

Start with a minimal configuration

On Linux, the XDG configuration directory is normally ~/.config/ghostty/. Save this as config. Back up an existing file and merge changes individually.

font-family = JetBrains Mono
font-size = 12
background-opacity = 1

The font family must exist. Check Linux font matching:

fc-match 'JetBrains Mono'

A different family in the result indicates fallback. CJK characters and icons may use separate fallback fonts; a regular monospace font need not contain Nerd Font symbols.

Comments must occupy their own lines:

# The compositor displays transparency; test opaque output first.
background-opacity = 0.92

An inline # comment becomes part of a setting's value. After editing, validate before testing the window:

ghostty +validate-config

Successful validation does not prove every font, protocol or platform effect works as intended. Configuration syntax and paths

Opacity, blur and decoration

Opacity reveals the background; blur changes its detail; decoration controls the title bar and borders. They are separate settings.

Hyprland can own rounding, blur and window movement while Ghostty requests no decoration:

window-decoration = none

Confirm usable window move, resize and close shortcuts before removing the title bar. background-blur has platform limitations; do not assume it creates a second independent blur layer under Hyprland. Option reference

If the terminal is translucent but Neovim remains opaque, the application may be painting its own background. Check application colours and terminal cell-background behaviour before increasing compositor blur.

From a theme file to visible colours

Only add this after ~/.config/ghostty/themes/MaterialYou exists:

theme = MaterialYou

The Matugen chapter explains generation. Writing the file and updating an existing window are separate steps. Check the file contents and modification time, then test Ghostty's reload action; some settings require a new window or application restart.

Explicit foreground/background colours can temporarily confirm that the expected configuration is being loaded. Do not send undocumented Unix signals to refresh Ghostty. Historical OSC broadcasting was an additional script, not an automatic Matugen guarantee.

Shell integration and SSH

Shell integration reports prompt boundaries, working directory and command status. Ghostty can inject it for supported shells, but custom launchers, remote shells and nested shells need separate checks.

Change directory and open another window to test directory tracking. Run successful and failing commands to check prompt-related behaviour. If commands work but tracking does not, inspect integration before modifying themes or PATH.

On the SSH remote host, inspect terminal identification:

printf '%s\n' "$TERM"
infocmp "$TERM"

An unknown-terminal error suggests missing terminfo. Install the matching definition; changing TERM arbitrarily declares capabilities that may not be accurate. Remote clipboard handling is covered in Neovim input and remote work.

Troubleshoot by symptom

Test CJK text, wide characters, colours and a full-screen program before adding Zellij. This provides a baseline for later failures.