Ghostty

Ghostty Skill

Overview

Ghostty is a fast, feature-rich, cross-platform terminal emulator that uses platform-native UI and GPU acceleration. It provides a CLI with +action commands for querying configuration, listing themes/fonts, validating config, and opening new windows via IPC. Window, tab, and split management are handled through keybind actions configured in the config file, not through CLI commands.

When to use: Configuring Ghostty themes, fonts, and keybinds; validating config files; querying available actions and themes; opening new windows from scripts; debugging terminal rendering issues.

When NOT to use: Managing other terminal emulators; tasks unrelated to terminal configuration.

Quick Reference

Common Mistakes

Delegation

• Discover available actions and themes: Use Explore agent to run ghostty +list-actions and ghostty +list-themes
• Automate terminal layouts: Use Task agent to script window creation and config changes
• Plan configuration changes: Use Plan agent to design keybind and theme configurations before applying

References

• CLI actions, flags, and IPC commands
• Configuration file, themes, fonts, keybinds, and debugging

CLI Actions

CLI Location

On macOS, Ghostty's CLI binary is inside the app bundle:

/Applications/Ghostty.app/Contents/MacOS/ghostty

If symlinked to your PATH, use ghostty directly. On Linux, it is typically available as ghostty after installation.

CLI Actions vs Keybind Actions

Ghostty has two distinct types of actions:

• CLI actions use the +action syntax on the command line (e.g., ghostty +list-themes)
• Keybind actions are configured in the config file and triggered by key combinations (e.g., keybind = ctrl+shift+t=new_tab)

These are separate systems. Not all keybind actions have CLI equivalents.

Available CLI Actions

Discovery and Inspection

List all keybind actions available for configuration:

ghostty +list-actions

Show general help and list all CLI actions:

ghostty +help

Get help for a specific action:

ghostty +list-themes --help

Theme Management

Browse and preview built-in themes in an interactive TUI:

ghostty +list-themes

Filter by color scheme:

ghostty +list-themes --color=dark
ghostty +list-themes --color=light

In the theme preview, press ? to list available keybindings. Press c to copy the selected theme name to the clipboard.

Font Management

List available fonts using Ghostty's font discovery:

ghostty +list-fonts

Show which font renders a specific Unicode codepoint:

ghostty +show-face U+1F600

Keybind Inspection

List current keybind configuration:

ghostty +list-keybinds

List only the built-in default keybinds:

ghostty +list-keybinds --default

Color Reference

List all named RGB colors:

ghostty +list-colors

Configuration

Show current configuration in valid config file format:

ghostty +show-config

Show all options with defaults and documentation:

ghostty +show-config --default --docs

Open config file in your editor ($VISUAL or $EDITOR):

ghostty +edit-config

Validate config file for errors:

ghostty +validate-config

IPC: New Window

Open a new window in a running Ghostty instance:

ghostty +new-window

Open a new window running a specific command:

ghostty +new-window -e htop

Open a new window in a specific GTK application instance:

ghostty +new-window --class=com.example.MyGhostty

Platform note: +new-window uses D-Bus IPC and only works on Linux/GTK. On macOS, Ghostty does not support this IPC mechanism. On Linux, D-Bus activation allows this to work even when Ghostty is not running.

SSH Terminfo

Manage SSH terminfo cache for remote hosts:

ghostty +ssh-cache

Crash Reports

Inspect and manage crash reports:

ghostty +crash-report

Fun

Display the animation from the Ghostty website:

ghostty +boo

Command-Line Flags

Running Commands

Execute a command inside the terminal:

ghostty -e htop
ghostty -e "bash -c 'echo hello && sleep 5'"

Working Directory

Start in a specific directory:

ghostty --working-directory=/path/to/project

Configuration

Load an additional config file:

ghostty --config-file=/path/to/custom-config

Any config option can be set via command-line flag:

ghostty --font-size=14 --font-family="JetBrains Mono" --theme=catppuccin-mocha

Display Info

ghostty --version
ghostty --help

GTK/Wayland Options

Set GTK application ID or Wayland app ID:

ghostty --class=com.example.MyGhostty

Disable single-instance mode to allow independent windows with custom config:

ghostty --gtk-single-instance=false --font-size=20

Configuration

Config File Location

Ghostty uses a plain-text key-value config file:

~/.config/ghostty/config

Configuration is optional. Without a config file, Ghostty uses sensible defaults. Use ghostty +edit-config to open the file in your editor.

Config File Format

The config file uses simple key = value syntax with no quotes needed for most values:

font-family = JetBrains Mono
font-size = 14
theme = catppuccin-mocha
cursor-style = block
window-padding-x = 8
window-padding-y = 8
background-opacity = 0.95

Lines starting with # are comments.

Themes

Ghostty ships with hundreds of built-in themes. Preview them interactively:

ghostty +list-themes

Set a theme in config:

theme = catppuccin-mocha

Use different themes for light and dark system appearance:

theme = light:catppuccin-latte,dark:catppuccin-mocha

Custom themes are placed in ~/.config/ghostty/themes/ as plain config files containing color definitions.

Font Configuration

List available fonts:

ghostty +list-fonts

Set font in config:

font-family = JetBrains Mono
font-size = 14

Set bold, italic, and bold-italic variants:

font-family = JetBrains Mono
font-family-bold = JetBrains Mono Bold
font-family-italic = JetBrains Mono Italic
font-family-bold-italic = JetBrains Mono Bold Italic

Keybind Configuration

Keybinds map key combinations to keybind actions:

keybind = ctrl+shift+t=new_tab
keybind = ctrl+shift+n=new_window
keybind = ctrl+shift+enter=new_split:right
keybind = ctrl+shift+minus=new_split:down
keybind = ctrl+shift+w=close_surface

Key Keybind Actions

Window and Tab Management

keybind = ctrl+shift+n=new_window
keybind = ctrl+shift+t=new_tab
keybind = ctrl+shift+page_up=previous_tab
keybind = ctrl+shift+page_down=next_tab
keybind = ctrl+shift+1=goto_tab:1
keybind = ctrl+shift+2=goto_tab:2
keybind = ctrl+end=last_tab
keybind = ctrl+shift+left=move_tab:-1
keybind = ctrl+shift+right=move_tab:1
keybind = ctrl+shift+o=toggle_tab_overview

Split Management

Create splits:

keybind = ctrl+shift+enter=new_split:right
keybind = ctrl+shift+minus=new_split:down
keybind = ctrl+shift+backslash=new_split:auto

Navigate between splits:

keybind = ctrl+shift+up=goto_split:up
keybind = ctrl+shift+down=goto_split:down
keybind = ctrl+shift+left=goto_split:left
keybind = ctrl+shift+right=goto_split:right
keybind = ctrl+tab=goto_split:next
keybind = ctrl+shift+tab=goto_split:previous

Resize splits:

keybind = super+shift+up=resize_split:up,10
keybind = super+shift+down=resize_split:down,10
keybind = super+shift+equal=equalize_splits

Zoom into a split:

keybind = ctrl+shift+z=toggle_split_zoom

Surface and Display

keybind = ctrl+shift+w=close_surface
keybind = f11=toggle_fullscreen
keybind = ctrl+shift+comma=reload_config

Font Size

keybind = ctrl+equal=increase_font_size:1
keybind = ctrl+minus=decrease_font_size:1
keybind = ctrl+0=reset_font_size

Unbinding Keys

Remove a default keybind:

keybind = ctrl+shift+t=unbind

Key Sequences

Chain multiple keypresses:

keybind = ctrl+a>1=goto_tab:1
keybind = ctrl+a>2=goto_tab:2

Command Palette

Ghostty includes a built-in command palette. Add custom entries with the command-palette-entry config key:

command-palette-entry = title:Reset Font Style, action:csi:0m
command-palette-entry = title:Crash Report, description:View crash reports, action:crash:main

Clear all default entries by setting to empty:

command-palette-entry =

The action syntax mirrors keybind actions.

Launch Command

Set the default command instead of the login shell:

command = /usr/bin/fish

Window Configuration

window-decoration = true
window-title-font-family = JetBrains Mono
window-padding-x = 8
window-padding-y = 8
window-padding-color = extend
confirm-close-surface = false
resize-overlay = never

Debugging

Validate your config for errors:

ghostty +validate-config

Show the fully resolved config (includes defaults):

ghostty +show-config

Show all options with documentation:

ghostty +show-config --default --docs

Check which font renders a specific character:

ghostty +show-face U+2603

Check version:

ghostty --version