Ghostty Documentation

Ghostty features are categorized into two types:

1. End-user features: Enhancements to the terminal experience that do not require changes to running applications (e.g., multi-window, tabs, splits, ligatures, auto-update).
2. Terminal application developer features: Protocols and capabilities that allow terminal applications to perform advanced tasks (e.g., Kitty graphics protocol, Kitty keyboard protocol, synchronized rendering, light/dark mode notifications).

Ghostty is cross-platform (macOS and Linux) and uses GPU-accelerated rendering (Metal on macOS, OpenGL on Linux).

The Ghostty documentation covers several key areas for users and developers:

• Keybindings: Learn how to use the keybind configuration option to create custom keyboard shortcuts.
• Color Themes: Explore built-in themes and how to configure light and dark mode support.
• Configuration: Access the full list of hundreds of configuration options to customize behavior and appearance.
• Terminal API (VT): For application developers, find references on terminal concepts and supported control sequences.

Ghostty's features are divided into two main categories:

Terminal Features

Capabilities available to programs running inside the terminal, such as:

• Kitty graphics protocol support
• Light/dark mode notifications
• Hyperlinks
• Support for advanced rendering (e.g., Neovim's synchronized rendering to prevent tearing)

Application Features

High-level features for interacting with the terminal emulator itself, such as:

• Native tabs and splits
• Drop-down terminal (macOS)
• Theme switching based on system dark/light mode
• Platform-specific integrations: macOS support for Quick Look, force touch, the macOS secure input API, and built-in window state recovery.

Escape sequences are a way to differentiate between text to be displayed and commands to be executed by writing bytes to the terminal's file descriptor. A true Escape sequence starts with the Escape character (0x1B or ESC) followed by intermediates and a final character.

Format:

esc_sequence = "0x1B" intermediates final
intermediates = [0x20-0x2F]*
final = [0x30-0x7E]

The SU operation is designed to preserve the pending wrap state. If a character is typed that would trigger a wrap, performing a Scroll Up operation does not reset that state.

cols=$(tput cols)
printf "\033[1;${cols}H" # move to top-right
printf "\033[2J" # clear screen
printf "A"
printf "\033[2;${cols}H"
printf "B"
printf "\033[3;${cols}H"
printf "C"
printf "\033[S"
printf "X"

The BEL character is a valid terminating character for Operating System Command (OSC) sequences, serving as an alternative to the preferred ST (String Terminator).

If you use BEL to terminate an OSC sequence in Ghostty, Ghostty will ensure that any responses generated by that sequence also terminate with the BEL character.

GTK single instance mode ensures that only one instance of Ghostty is running at a time. When enabled, launching a second instance of Ghostty will cause the original instance to create a new window and gain focus, while the second process terminates. This mode is the idiomatic behavior for GNOME applications and significantly improves startup performance and reduces memory usage for subsequent windows, as it avoids the overhead of initializing the GTK framework multiple times.

Ghostty enables this mode by default only when it is not launched from a CLI environment. It uses two heuristics to decide when to disable single instance mode:

1. If the TERM_PROGRAM environment variable is set to any non-empty value (assuming a graphical terminal emulator).
2. If any command line arguments are passed to the ghostty command (assuming instance-specific configuration is required).

You can reference themes in two ways:

1. By Absolute Path: Provide the full path to the file in the theme configuration option.
2. By Name: If you want to use a theme name (e.g., theme = MyTheme), the file must be located in one of these directories:
   • $XDG_CONFIG_HOME/ghostty/themes
   • $PREFIX/share/ghostty/themes

Ghostty operates under a BDFL (Benevolent Dictator for Life) model.

• Project Lead: Mitchell Hashimoto serves as the final authority on all decisions, including the direction of funds (within the bounds of the non-profit mission).
• Oversight: Hack Club provides financial and legal oversight to ensure activities align with non-profit mission and legal obligations.
• License: The project is licensed under the MIT license.

Programs running in Ghostty interact with the terminal using control sequences, also known as VT sequences or escape codes. These are series of special characters that the terminal interprets as commands rather than literal text.

To build applications for Ghostty, you must use these sequences to control terminal behavior, such as cursor movement, text styling, or screen manipulation. For specific implementation details, refer to the Ghostty VT reference documentation.

Ghostty is built using a decoupled architecture that separates terminal emulation from the user interface. The core of the project is libghostty, a cross-platform, C-ABI compatible library written in Zig.

libghostty provides the following core capabilities:

• Terminal emulation
• Font handling
• Rendering capabilities

The Ghostty GUI applications (macOS and Linux) act as consumers of this library. This architecture allows the terminal core to be reused by other terminal emulator projects, enabling them to focus on high-level features and UIs without reimplementing the core emulation logic.

Note: As of the initial public release, libghostty is not yet a stable API and has not been released as a standalone, stable library. It is currently used internally by the macOS and Linux GUI applications.

The Save Cursor (DECSC) sequence allows you to save the current cursor state so it can be restored later using the Restore Cursor (DECRC) sequence.

Saved Attributes:

• Cursor row and column (absolute screen coordinates)
• Character sets
• Pending wrap state
• SGR attributes
• Origin mode (DEC Mode 6)

Key Behaviors:

• Single Slot: Only one cursor state can be saved at a time. Repeating the save command overwrites the previous state.
• Screen Isolation: Primary and alternate screens maintain separate saved cursor states. A cursor saved on the primary screen cannot be restored while in the alternate screen, and vice versa.

Sequences:

• Save Cursor (DECSC): ESC 7 (or [7 / 7)
• Restore Cursor (DECRC): ESC 8 (or [8 / 8)

printf "\0337" # Save Cursor
printf "\0338" # Restore Cursor