| name | ghostty |
| description | Controls the Ghostty terminal emulator via CLI actions and configuration. Use when managing Ghostty windows, fonts, themes, keybinds, config validation, or debugging terminal configuration. Use for ghostty CLI, terminal config, theme selection, font management. |
| license | MIT |
| metadata | {"author":"oakoss","version":"1.1","source":"https://ghostty.org/docs"} |
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
