Skip to main content
skill CX Codex

ghostty-config — Claude Code skill: what it does, how to install

ghostty-config is a Claude Code skill that configures and troubleshoots Ghostty terminal files, including keybind syntax, CLI actions, and Linux/macOS differences.

Apache-2.0 ★ 173 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sammcj/agentic-coding --skill ghostty-config -a claude-code
Open on GitHub

What ghostty-config does

This skill equips Claude Code with knowledge of Ghostty terminal configuration files (config.ghostty and legacy config). It explains file lookup priority across XDG directories and macOS Application Support paths, where macOS settings override XDG files. The reference covers key accumulation, config-file includes, and helper actions such as ghostty +validate-config or ghostty +list-themes.

It also provides format rules for complex shortcuts, including key sequences and prefixes like global: or performable:. Platform-specific flags fail silently on the wrong operating system, which makes strict OS validation necessary before saving the configuration.

What it helps with

  • write keybindings and multi-key sequences in config.ghostty
  • set up dual light and dark themes with automatic switching
  • troubleshoot Ghostty configuration errors using CLI commands
  • disable font ligatures using font-feature flags

Example prompts for the agent

  • Configure Ghostty on macOS with separate light and dark Catppuccin themes
  • Add a keybinding sequence for opening a new window in Ghostty
  • Validate my config.ghostty and fix any invalid syntax

How to install ghostty-config

1Skills CLI (Vercel)

npx skills add sammcj/agentic-coding --skill ghostty-config -a claude-code

2Manually: put the files in place

~/.claude/skills/ghostty-config/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ghostty-config/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ghostty-config

How do I install ghostty-config in Claude Code?

Run npx skills add sammcj/agentic-coding --skill ghostty-config -a claude-code. Alternatively, place the skill definition file directly into ~/.claude/skills/ghostty-config/SKILL.md.

What does ghostty-config do?

It guides the agent through Ghostty config syntax, CLI helper tools, hotkey declarations, and operating system specifics.

Why did an option in config.ghostty have no effect?

Ghostty silently ignores configuration options restricted to another operating system without showing any error message.

Source text

SKILL.md · Apache-2.0
---
name: ghostty-config
description: Use when creating, editing or debugging Ghostty terminal configuration - config.ghostty files, config option names and their valid values, keybinds and key sequences, themes, fonts, shell integration, or `ghostty +` CLI actions. Covers macOS and Linux/GTK differences.
metadata:
  config_schema_last_updated: "2026-05-20" # Update when realigning the skill with the latest config schema JSON
---

# Ghostty Configuration

## Config File Locations

Config is optional; with no file Ghostty runs on its defaults. Since Ghostty 1.2.3 the file is named `config.ghostty`; extensionless `config` still loads for backwards compatibility.

- XDG (all platforms): `$XDG_CONFIG_HOME/ghostty/config.ghostty`, then `$XDG_CONFIG_HOME/ghostty/config`. `XDG_CONFIG_HOME` defaults to `~/.config`.
- macOS also: `~/Library/Application Support/com.mitchellh.ghostty/config.ghostty`, then `.../config`.

Every matching file loads, later files overriding earlier ones. Within a location `config.ghostty` loads before `config`. On macOS the macOS-path files load after the XDG ones, so macOS paths win on conflict.

## Syntax

```
# Comments start with #
background = 282c34
font-family = "JetBrains Mono"
keybind = ctrl+z=close_surface
font-family =                     # Empty value resets to default
```

- Keys are case-sensitive: use lowercase.
- Repeatable keys (`font-family`, `keybind`, `palette`, `env`, `link`) accumulate across lines.
- Every config key doubles as a CLI flag: `ghostty --background=282c34 --font-size=14`.

## Includes

```
config-file = themes/dark.conf
config-file = ?local.conf       # ? prefix = optional, no error if missing
```

`config-file` directives are processed at the end of the containing file, so keys written after one still lose to the included file's values. Put overrides in the included file, or include first and keep the parent free of conflicting keys.

## Applying Changes

- Reload: `ctrl+shift+,` (Linux), `cmd+shift+,` (macOS). Some options need a restart; some apply only to newly created terminals.
- Validate after every edit: `ghostty +validate-config`.

## CLI Actions

`ghostty +<action>`; add `--help` for per-action help.

| Command                                 | Purpose                                       |
|-----------------------------------------|-----------------------------------------------|
| `ghostty +validate-config`              | Check the config for errors                   |
| `ghostty +show-config`                  | Show the effective configuration              |
| `ghostty +show-config --default --docs` | Show defaults with documentation              |
| `ghostty +edit-config`                  | Open the config in the default editor         |
| `ghostty +list-fonts`                   | Available fixed-width fonts                   |
| `ghostty +list-themes`                  | Available colour themes                       |
| `ghostty +list-colors`                  | Available X11 colour names                    |
| `ghostty +list-keybinds`                | Current keybinds (`--default` for defaults)   |
| `ghostty +list-actions`                 | All keybind actions                           |
| `ghostty +show-face`                    | Font face information                         |
| `ghostty +ssh-cache`                    | Manage the SSH terminfo cache                 |
| `ghostty +new-window`                   | Open a new window (Linux only)                |

On macOS the `ghostty` binary is a helper tool: launch the terminal with `open -na Ghostty.app`, passing flags as `open -na Ghostty.app --args --font-size=14`. Use `ghostty -e <command>` to run a command in a new terminal.

## Keybind Syntax

Format: `keybind = [prefix:]trigger=action[:param]`

Modifiers: `shift`, `ctrl`/`control`, `alt`/`opt`/`option`, `super`/`cmd`/`command`.

```
keybind = ctrl+shift+t=new_tab
keybind = super+backquote=toggle_quick_terminal
keybind = ctrl+a>n=new_window          # Sequence: press ctrl+a, release, press n
keybind = clear                        # Remove ALL keybinds, including defaults
keybind = ctrl+a=unbind                # Remove one binding
keybind = ctrl+a=ignore                # Ghostty and the terminal both ignore the key
```

- Physical keys use W3C codes (`KeyA`, `key_a`, `Digit1`, `BracketLeft`) and outrank unicode codepoints. Prefer them for non-US layouts.
- Sequences wait indefinitely for the next key.

| Prefix         | Effect                                                                                |
|----------------|---------------------------------------------------------------------------------------|
| `global:`      | System-wide (macOS: needs Accessibility permission; Linux: needs an XDG Desktop Portal) |
| `all:`         | Applies to all terminal surfaces                                                      |
| `unconsumed:`  | Passes the input through as well                                                      |
| `performable:` | Consumes the input only if the action succeeds                                        |

Prefixes combine: `global:unconsumed:ctrl+a=reload_config`. Sequences work with `unconsumed:`/`performable:` but not with `global:` or `all:`.

Ghostty 1.3+ adds modal key tables and in-terminal search actions - see `references/keybindings.md`.

## Gotchas

- Confirm an option's platform before recommending it: the reference tables carry platform markers, and an option gated to another platform silently does nothing.
- `theme` accepts mode switching: `theme = light:catppuccin-latte,dark:catppuccin-mocha`.
- Disable ligatures with `font-feature = -calt` plus `font-feature = -liga`.
- Prefer a theme name from `ghostty +list-themes` over hand-written colours when the user asks for a known theme.

## References

Load one when the task needs it - each is a lookup catalogue, not background reading:

- Naming or checking an option for fonts, colours and themes, cursor appearance, selection or search-match colours, transparency, background images, shaders, cell metrics, scrollbar, window geometry/padding/decoration/startup state, tabs, splits or the quick terminal -> `references/options-appearance.md`
- Naming or checking an option for shell and command startup, shell integration, clipboard, scrollback, mouse (including cursor click-to-move), modifier remapping via `key-remap`, bell, notifications, links, app lifecycle, or the `macos-*`, `gtk-*`, `adw-*` and `linux-*` prefixed families -> `references/options-behaviour.md`
- Naming a keybind action, its `:param` form, key tables or search actions -> `references/keybindings.md`

Platform-gated options sit with their domain, not in a platform bucket: `font-thicken` (macOS) and `window-vsync` (macOS) are in the appearance file. Only the prefixed families above live in the platform sections.

The current schema (including tip releases) is at https://raw.githubusercontent.com/sammcj/vscode-ghostty-config-syntax/refs/heads/main/schema/ghostty-config-syntax.schema.json - large, so query it programmatically rather than reading it whole.

© sammcj · Apache-2.0 · sammcj/agentic-coding

Similar skills

All skills for Notes, tasks and projects →

From the same set73

The whole set →
step-back step-back — a subagent that checks if your current approach is over-engineered. Analyzes code or design and returns one verdict: continue, simplify, or restart. CX Codex ★ 173repo stars reframe-voice reframe-voice guides long-form thought-leadership writing with an evidence-based perspective. Activates when you explicitly need a deep essay without marketing hype. CX Codex +1 ★ 173repo stars excalidraw-diagrams Builds and edits Excalidraw diagrams using MCP previews or standalone Python generation scripts. CX Codex +1 ★ 173repo stars idrive-backup Inspect and manage iDrive Backup settings on macOS, from exclusion rules to backup paths. The bundled tool saves configuration copies before making changes. CX Codex +1 ★ 173repo stars release-debrief release-debrief compares a supported tool’s newest release with the last saved debrief. Use it to catch changes in Claude Code, OpenCode, llama-swap, or llama.cpp. CX Codex +1 ★ 173repo stars pptx-to-md pptx-to-md turns PPTX into per-slide Markdown files, preserving text, image positions, and descriptions of diagrams and screenshots. Useful when you need structured deck content with interpreted visuals. CX Codex +1 ★ 173repo stars web-artifacts-builder-v2 web-artifacts-builder-v2 builds multi-component HTML artifacts with React, including interfaces that need state or routing. Use it to turn a frontend project into a standalone HTML file. CX Codex +1 ★ 173repo stars glean-cli Teaches the agent to drive the glean CLI: search the corporate index, query Glean Assistant, pull documents and people, manage collections. CX Codex +1 ★ 173repo stars

Project sponsors

Companies that keep this analytics open