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

Task	Command / Config	Key Points
List CLI actions	`ghostty +list-actions`	Shows keybind actions, not CLI actions
List themes	`ghostty +list-themes`	Interactive TUI preview; `--color=dark` to filter
List fonts	`ghostty +list-fonts`	Uses Ghostty's font discovery
List keybinds	`ghostty +list-keybinds`	Add `--default` for defaults only
List colors	`ghostty +list-colors`	Named RGB colors available in config
Show config	`ghostty +show-config`	Add `--default --docs` for all options
Validate config	`ghostty +validate-config`	Check config file for errors
Edit config	`ghostty +edit-config`	Opens config in `$VISUAL` or `$EDITOR`
New window (IPC)	`ghostty +new-window`	Linux/GTK only via D-Bus; use `-e` for command
Run command	`ghostty -e htop`	Arguments after `-e` are the command
Set working dir	`ghostty --working-directory=/path`	Changes directory before running command
Custom config	`ghostty --config-file=/path`	Load additional config file
Check version	`ghostty --version`	Display version info
SSH terminfo	`ghostty +ssh-cache`	Manage SSH terminfo cache for remote hosts
Show font face	`ghostty +show-face <codepoint>`	Which font renders a specific Unicode codepoint
Crash reports	`ghostty +crash-report`	Inspect and manage crash reports

Common Mistakes

Mistake	Correct Pattern
Running `ghostty +new-tab` or `+new-split` as CLI commands	These are keybind actions, not CLI actions; configure them in the config file with `keybind = ...`
Running `ghostty` without full path when not symlinked on macOS	Use `/Applications/Ghostty.app/Contents/MacOS/ghostty` or create a symlink
Using `+new-window` on macOS expecting it to work	`+new-window` uses D-Bus IPC and only works on Linux/GTK
Editing config without reloading	Use the `reload_config` keybind action (default: `ctrl+shift+comma` on Linux)
Using `--config-file` with a relative path	Use absolute paths for `--config-file` to avoid resolution issues
Passing unknown actions without checking available list	Run `ghostty +help` to see CLI actions or `+list-actions` for keybind actions
Confusing CLI actions with keybind actions	CLI actions use `+action` syntax; keybind actions are configured via `keybind = key=action` in config

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](references/cli-actions.md)
[Configuration file, themes, fonts, keybinds, and debugging](references/configuration.md)

ghostty

Installation

Similar popular skills

Also in this package

Agent compatibility

Also listed on

Repository health

Skill metadata

Package contents

History

SKILL.md