GHOSTTY(5)
💅 ghostty(5) — the Ghostty terminal emulator config file, but make it make sense
okay so this is ghostty(5), the manual page for the Ghostty terminal emulator configuration file, and bestie i'm gonna walk you through every single line of it. no skimming, no "you'll figure it out" — we're doing this together 🫶
✨ NAME ✨
ghostty — the Ghostty terminal emulator configuration file. that's it, that's the name, short and iconic 👑
🌸 DESCRIPTION 🌸
so to configure Ghostty you must use a configuration file. like, actually. GUI-based configuration is on the roadmap but not yet supported, so no vibes-based clicking for now, sorry 😭
The configuration file must be placed at $XDG_CONFIG_HOME/ghostty/config.ghostty, which defaults to ~/.config/ghostty/config.ghostty if the XDG environment is not set.
If you're on macOS (hiii 🍎), the configuration file can also be placed at $HOME/Library/Application Support/com.mitchellh.ghostty/config.ghostty. This is the default configuration location for macOS. It will be searched before any of the XDG environment locations listed above.
The file format is documented below as an example — this is literally the manpage's own example, copy it, live in it, love it:
# The syntax is "key = value". The whitespace around the equals doesn't matter.
background = 282c34
foreground= ffffff
# Blank lines are ignored!
keybind = ctrl+z=close_surface
keybind = ctrl+d=new_split:right
# Colors can be changed by setting the 16 colors of `palette`, which each color
# being defined as regular and bold.
#
# black
palette = 0=#1d2021
palette = 8=#7c6f64
# red
palette = 1=#cc241d
palette = 9=#fb4934
# green
palette = 2=#98971a
palette = 10=#b8bb26
# yellow
palette = 3=#d79921
palette = 11=#fabd2f
# blue
palette = 4=#458588
palette = 12=#83a598
# purple
palette = 5=#b16286
palette = 13=#d3869b
# aqua
palette = 6=#689d6a
palette = 14=#8ec07c
# white
palette = 7=#a89984
palette = 15=#fbf1c7You can view all available configuration options and their documentation by executing the command ghostty +show-config --default --docs. 🎀 Heads up though: this will output the full default configuration with docs to stdout, so you may want to pipe that through a pager, an editor, etc. (your scrollback will simply not survive it, ngl)
Note: You'll see a lot of weird blank configurations likefont-family =. This is a valid syntax to specify the default behavior (no value). The+show-configoutputs it so it's clear that key is defaulting and also to have something to attach the doc comment to. it's not a bug, it's a choice, and honestly? valid 💅
You can also see and read all available configuration options in the source Config structure. The available keys are the keys verbatim, and their possible values are typically documented in the comments. You also can search for the public config files of many Ghostty users for examples and inspiration. (yes, looking at other people's dotfiles is a love language 🦋)
🐛 Configuration Errors
If your configuration file has any errors, Ghostty does its best to ignore them and move on. Configuration errors will be logged. it's giving "not mad, just disappointed, and also it's in the log" 😭
🔍 Debugging Configuration
You can verify that configuration is being properly loaded by looking at the debug output of Ghostty.
In the debug output, you should see in the first 20 lines or so messages about loading (or not loading) a configuration file, as well as any errors it may have encountered. Configuration errors are also shown in a dedicated window on both macOS and Linux (GTK). Ghostty does not treat configuration errors as fatal and will fall back to default values for erroneous keys. so your terminal will not explode, it'll just quietly do its own thing 🫶
You can also view the full configuration Ghostty is loading using ghostty +show-config from the command-line. Use the --help flag for additional options for that command.
📝 Logging
Ghostty can write logs to a number of destinations. On all platforms, logging to stderr is available. Depending on the platform and how Ghostty was launched, logs sent to stderr may be stored by the system and made available for later retrieval.
On Linux, if Ghostty is launched by the default systemd user service, you can use journald to see Ghostty's logs:
journalctl --user --unit app-com.mitchellh.ghostty.serviceOn macOS, logging to the macOS unified log is available and enabled by default. Use the system log CLI to view Ghostty's logs:
sudo log stream --level debug --predicate 'subsystem=="com.mitchellh.ghostty"'Ghostty's logging can be configured in two ways. The first is by what optimization level Ghostty is compiled with. If Ghostty is compiled with Debug optimizations, debug logs will be output to stderr. If Ghostty is compiled with any other optimization, the debug logs will not be output to stderr.
Ghostty also checks the GHOSTTY_LOG environment variable. It can be used to control which destinations receive logs. Ghostty currently defines two destinations:
stderr— logging tostderr.macos— logging to macOS's unified log (has no effect on non-macOS platforms).
Combine values with a comma to enable multiple destinations. Prefix a destination with no- to disable it. Enabling and disabling destinations can be done at the same time. Setting GHOSTTY_LOG to true will enable all destinations. Setting GHOSTTY_LOG to false will disable all destinations. chef's kiss, so much control 🌈
👑 CONFIGURATION OPTIONS 👑
okay this is the main character section, buckle up bestie
language— Set Ghostty's graphical user interface language to a language other than the system default language. For example:
language = dewill force the strings in Ghostty's graphical user interface to be in German rather than the system default.
This will not affect the language used by programs run within Ghostty. Those will continue to use the default system language 🫶 There are also many non-GUI elements in Ghostty that are not translated — this setting will have no effect on those.
Warning: This setting cannot be reloaded at runtime. To change the language you must fully restart Ghostty. like, a full goodbye-and-hello, not a lil reload 😭
GTK only. Available since 1.3.0.
font-family— The font families to use.
You can generate the list of valid values using the CLI:
ghostty +list-fontsThis configuration can be repeated multiple times to specify preferred fallback fonts when the requested codepoint is not available in the primary font. This is particularly useful for multiple languages, symbolic fonts, etc. ✨
Notes on emoji specifically: On macOS, Ghostty by default will always use Apple Color Emoji and on Linux will always use Noto Emoji. You can override this behavior by specifying a font family here that contains emoji glyphs. (emoji girlies stay winning 🍓)
The specific styles (bold, italic, bold italic) do not need to be explicitly set. If a style is not set, then the regular style (font-family) will be searched for stylistic variants. If a stylistic variant is not found, Ghostty will use the regular style. This prevents falling back to a different font family just to get a style such as bold. This also applies if you explicitly specify a font family for a style. For example, if you set font-family-bold = FooBar and "FooBar" cannot be found, Ghostty will use whatever font is set for font-family for the bold style.
Finally, some styles may be synthesized if they are not supported. For example, if a font does not have an italic style and no alternative italic font is specified, Ghostty will synthesize an italic style by applying a slant to the regular style. If you want to disable these synthesized styles then you can use the font-style configurations as documented below.
You can disable styles completely by using the font-style set of configurations. See the documentation for font-style for more information.
If you want to overwrite a previous set value rather than append a fallback, specify the value as "" (empty string) to reset the list and then set the new values. For example:
font-family = ""
font-family = "My Favorite Font"Setting any of these as CLI arguments will automatically clear the values set in configuration files so you don't need to specify --font-family="" before setting a new value. You only need to specify this within config files if you want to clear previously set values in configuration files or on the CLI if you want to clear values set on the CLI.
font-family-boldfont-family-italicfont-family-bold-italicfont-style— The named font style to use for each of the requested terminal font styles. This looks up the style based on the font style string advertised by the font itself. For example, "Iosevka Heavy" has a style of "Heavy".
You can also use these fields to completely disable a font style. If you set the value of the configuration below to literal false then that font style will be disabled. If the running program in the terminal requests a disabled font style, the regular font style will be used instead.
These are only valid if its corresponding font-family is also specified. If no font-family is specified, then the font-style is ignored unless you're disabling the font style.
font-style-boldfont-style-italicfont-style-bold-italicfont-synthetic-style— Control whether Ghostty should synthesize a style if the requested style is not available in the specifiedfont-family.
Ghostty can synthesize bold, italic, and bold italic styles if the font does not have a specific style. For bold, this is done by drawing an outline around the glyph of varying thickness. For italic, this is done by applying a slant to the glyph. For bold italic, both of these are applied.
Synthetic styles are not perfect and will generally not look as good as a font that has the style natively. However, they are useful to provide styled text when the font does not have the style.
Set this to "false" or "true" to disable or enable synthetic styles completely. You can disable specific styles using "no-bold", "no-italic", and "no-bold-italic". You can disable multiple styles by separating them with a comma. For example, "no-bold,no-italic".
Available style keys are: bold, italic, bold-italic.
If synthetic styles are disabled, then the regular style will be used instead if the requested style is not available. If the font has the requested style, then the font will be used as-is since the style is not synthetic. 💜
okay that's the setup part and the first handful of options handled — and there is so much more config to get through, so stay with me bestie, we're literally just getting started ✨🎀
⚠️ Warning: the easiest mistake in the world is disabling bold or italic but not bold-italic. Disabling just bold or just italic will NOT disable either one in the bold-italic style. If you actually want bold-italic gone, you have to explicitly disable it — you cannot partially disable bold-italic. Periodt.
By default, synthetic styles are enabled. ✨
font-feature
Apply a font feature. Want more than one? Just repeat this config multiple times, or hit it with a comma-separated list of feature settings. 💅
The syntax for feature settings goes like this, where feat is a feature:
- Enable features with e.g.
feat,+feat,feat on,feat=1. - Disable features with e.g.
-feat,feat off,feat=0. - Set a feature value with e.g.
feat=2,feat = 3,feat 4. - Feature names may be wrapped in quotes, meaning this config should be syntactically compatible with the
font-feature-settingsCSS property.
The syntax is pretty loose ngl, but invalid settings will be silently ignored — like, no error, just nothing. 🙈
The font feature applies to all fonts rendered by Ghostty. A future enhancement will allow targeting specific faces (not yet though!).
To disable programming ligatures, use -calt, since that's the typical feature name for programming ligatures. Wanna know what font features your font even has and what they do? Use a font inspection tool such as fontdrop.info. 🔍
To generally disable most ligatures, use -calt, -liga, -dlig.
font-size
Font size in points. This value can be a non-integer, and the nearest integer pixel size will be selected. Living that high-dpi life where 1pt = 2px? Then you can get an odd numbered pixel size by specifying a half point. 🎀
For example: 13.5pt @ 2px/pt = 27px
Changing this at runtime only affects existing terminals that have NOT manually adjusted their font size in some way (like bumping it up or down). Terminals that did manually adjust their size keep their manually adjusted size. Otherwise, the font size of existing terminals updates on reload.
On Linux with GTK, font size is scaled according to both display-wide and text-specific scaling factors, which are often managed by your desktop environment (e.g. the GNOME display scale and large text settings). 🐧
font-variation
A repeatable configuration to set one or more font variation values for a variable font. A variable font is a single font — usually with a filename ending in -VF.ttf or -VF.otf — that contains one or more configurable axes for things like weight, slant, etc. Not all fonts support variations; only fonts that explicitly state they're variable fonts will work. 💀
The format is id=value where id is the axis identifier. An axis identifier is always a 4 character string, such as wght. To get the list of supported axes, look at your font documentation or use a font inspection tool.
Invalid ids and values are usually ignored. For example, if a font only supports weights from 100 to 700, setting wght=800 will do nothing (it will not be clamped to 700). You must consult your font's documentation to see what values are supported. No guessing, bestie.
Common axes are: wght (weight), slnt (slant), ital (italic), opsz (optical size), wdth (width), GRAD (gradient), etc.
font-variation-bold
font-variation-italic
font-variation-bold-italic
Same vibe as font-variation above 👆 — these are the bold, italic, and bold-italic faces of it. 🫶
font-codepoint-map
Force one codepoint, or a whole range of Unicode codepoints, to map to a specific named font. This is useful if you want to support special symbols, or if you want specific glyphs that render better in your specific font. 🦋
The syntax is codepoint=fontname where codepoint is either a single codepoint or a range. Codepoints must be specified as full Unicode hex values, such as U+ABCD. Codepoint ranges are specified as U+ABCD-U+DEFG. You can specify multiple ranges for the same font separated by commas, like U+ABCD-U+DEFG,U+1234-U+5678=fontname. The font name is the same value you'd use for font-family.
This configuration can be repeated multiple times to specify multiple codepoint mappings.
Changing this at runtime only affects new terminals — i.e. new windows, tabs, etc. Existing ones stay as they were.
clipboard-codepoint-map
Map specific Unicode codepoints to replacement values when copying text to the clipboard. 📋
This lets you swap specific Unicode characters for other characters or strings when copying terminal content to the clipboard. It's useful for converting special terminal symbols into more compatible characters for pasting into other apps. The syntax is similar to font-codepoint-map:
- Single codepoint:
U+1234=U+ABCDorU+1234=replacement_text - Codepoint range:
U+1234-U+5678=U+ABCD
Examples:
clipboard-codepoint-map = U+2500=U+002D(box drawing horizontal → hyphen)clipboard-codepoint-map = U+2502=U+007C(box drawing vertical → pipe)clipboard-codepoint-map = U+03A3=SUM(Greek sigma → "SUM")
This configuration can be repeated multiple times to specify multiple mappings. Later entries take priority over earlier ones for overlapping ranges. 👑
Note: this only applies to text copying operations, not URL copying.
font-thicken
Draw fonts with a thicker stroke, if supported. This is currently only supported on macOS. 🍎
font-thicken-strength
Strength of thickening when font-thicken is enabled.
Valid values are integers between 0 and 255. Careful though — 0 does not correspond to no thickening, rather it corresponds to the lightest available thickening. 😭
Has no effect when font-thicken is set to false.
This is currently only supported on macOS.
font-shaping-break
Locations to break font shaping into multiple runs.
A "run" is a contiguous segment of text that is shaped together. "Shaping" is the process of converting text (codepoints) into glyphs (renderable characters). This is how ligatures are formed, among other things. For example, if a coding font turns "!=" into a single glyph, then it must see "!" and "=" next to each other in a single run. When a run is broken, the text is shaped separately. To continue our example, if "!" is at the end of one run and "=" is at the start of the next run, then the ligature will not be formed. 🧚
Ghostty breaks runs at certain points to improve readability or usability. For example, Ghostty by default will break runs under the cursor so that text editing can see the individual characters rather than a ligature. This configuration lets you configure this behavior.
Combine values with a comma to set multiple options. Prefix an option with no- to disable it. Enabling and disabling options can be done at the same time. ✨
Available options:
cursor— Break runs under the cursor.
Available since: 1.2.0
alpha-blending
What color space to use when performing alpha blending.
This affects the appearance of text and of any images with transparency. Additionally, custom shaders will receive colors in the configured space. 🌈
On macOS the default is native, on all other platforms the default is linear-corrected.
Valid values:
native— Perform alpha blending in the native color space for the OS. On macOS this corresponds to Display P3, and on Linux it's sRGB.linear— Perform alpha blending in linear space. This will eliminate the darkening artifacts around the edges of text that are very visible when certain color combinations are used (e.g. red / green), but makes dark text look much thinner than normal and light text much thicker. This is also sometimes known as "gamma correction".linear-corrected— Same aslinear, but with a correction step applied for text that makes it look nearly or completely identical tonative, but without any of the darkening artifacts.
Available since: 1.1.0
adjust-cell-width
Okay so all of the adjust-* configurations adjust various metrics determined by the font. The values can be integers (1, -1, etc.) or a percentage (20%, -15%, etc.). In every case, the values represent the amount to change the original value. 📏
For example, a value of 1 increases the value by 1; it does not set it to literally 1. A value of 20% increases the value by 20%. And so on.
⚠️ There is little to no validation on these values, so the wrong values (e.g. -100%) can cause the terminal to be unusable. Use with caution and reason, bestie. 💀
Some values are clamped to minimum or maximum values. This can make it appear that certain values are ignored. For example, many *-thickness adjustments cannot go below 1px.
adjust-cell-height has some additional behaviors to describe:
- The font will be centered vertically in the cell.
- The cursor will remain the same size as the font, but may be adjusted separately with
adjust-cursor-height. - Powerline glyphs will be adjusted along with the cell height so that things like status lines continue to look aligned. 🔥
adjust-cell-height
Yep — that's the one we just described up there 👆. See the extra behaviors listed under adjust-cell-width.
adjust-font-baseline
Distance in pixels or percentage adjustment from the bottom of the cell to the text baseline. Increase to move baseline UP, decrease to move baseline DOWN. See the notes about adjustments in adjust-cell-width. ⬆️⬇️
adjust-underline-position
Distance in pixels or percentage adjustment from the top of the cell to the top of the underline. Increase to move underline DOWN, decrease to move underline UP. See the notes about adjustments in adjust-cell-width.
adjust-underline-thickness
Thickness in pixels of the underline. See the notes about adjustments in adjust-cell-width. 🎀
adjust-strikethrough-position— how far you nudge the strikethrough from the top of the cell to the top of the line itself, in pixels or as a percentage. Bump it up to move the strikethrough DOWN, bring it down to move it UP. The whole adjustments lore lives over inadjust-cell-width, go read that 🫶adjust-overline-position— same deal but for the overline, bestie: distance in pixels or percentage from the top of the cell to the top of the overline. Increase = overline scoots DOWN, decrease = it floats UP. Adjustment notes?adjust-cell-width. ✨adjust-strikethrough-thickness— how thicc the strikethrough is, in pixels or as a percentage adjustment. Adjustment notes again inadjust-cell-width💅adjust-overline-thickness— thickness of the overline, pixels or percentage adjustment. Yep, you know the drill:adjust-cell-widthhas the adjustment notes 🌸adjust-cursor-thickness— thickness of the bar cursor and the outlined rect cursor, in pixels or percentage adjustment. Notes about adjustments →adjust-cell-width🎀adjust-cursor-height— height of the cursor, pixels or percentage adjustment. Currently this hits all cursor types: bar, rect, and outlined rect. Adjustment notes live inadjust-cell-width🦋adjust-box-thickness— thickness of your box drawing characters, in pixels or percentage adjustment. Adjustment notes, once more, inadjust-cell-width🫶adjust-icon-height— height, in pixels or percentage adjustment, of the maximum height for nerd font icons 🔥
A positive value raises (and a negative value lowers) that max icon height. Heads up though, it might not hit every icon equally — the effect depends on whether the default size of the icon is height-constrained, which itself depends on the aspect ratio of both the icon and your primary font. So it's giving "it depends" energy, lowkey 🙈
Certain icons built for box drawing and terminal graphics — Powerline symbols, for example — are not affected by this option.
See the notes about adjustments in adjust-cell-width.
Available in: 1.2.0
grapheme-width-method— which method gets used to figure out the cell width of a grapheme cluster. Default isunicode, which uses the Unicode standard to determine grapheme width. Correct widths, yes, but it can cause cursor-desync issues with some programs (shells, looking at you 😭) that use a legacy method likewcswidth.
Valid values are:
legacy— use a legacy method to determine grapheme width, likewcswidth. Maximum compatibility with legacy programs, but you may get incorrect grapheme width for certain graphemes: skin-tone emoji, non-English characters, that whole situation.
It's called "legacy" and not something more specific on purpose — the behavior is undefined and they want to keep the freedom to change it. Like, they may or may not use libc wcswidth now or in the future. No cap.
unicode— use the Unicode standard to determine grapheme width.
If a running program explicitly enables terminal mode 2027, then unicode width gets forced no matter what this config says. When mode 2027 is reset, this config comes back into play 👑
This can be changed at runtime, but it will not affect terminals that already exist. Only new terminals pick up the new config ✨
freetype-load-flags— which FreeType load flags to enable. Format is a list of flags separated by commas. Prefix a flag withno-and it's disabled. Omit a flag and its default value is used, so you must explicitly disable the flags you don't want. You can also usetrueorfalseto flip them all on or off 🎀
This only applies to Ghostty builds that use FreeType — usually just Linux builds. macOS uses CoreText and has no equivalent config. Sorry Apple girlies 💅
Available flags:
hinting— enable or disable hinting. Enabled by default.force-autohint— always use the FreeType auto-hinter instead of the font's native hinter. Disabled by default.monochrome— tells the renderer to use 1-bit monochrome rendering. This kills anti-aliasing, and honestly it probably will not look very good unless you're using a pixel font. Disabled by default 👀autohint— enable the FreeType auto-hinter. Enabled by default.light— use a light hinting style, which preserves glyph shapes better. It's the most common setting in GTK apps, which is why it's also Ghostty's default. Has no effect ifmonochromeis enabled. Enabled by default.
Example: hinting, no-hinting, force-autohint, no-force-autohint
theme— a theme to use 🎨 This can be a built-in theme name, a custom theme name, or an absolute path to a custom theme file. Ghostty also lets you set a different theme for light mode and dark mode. Each option is documented below.
If the theme is an absolute pathname, Ghostty tries to load that file as a theme. If that file doesn't exist or can't be accessed, an error gets logged and no other directories are searched.
If the theme isn't an absolute pathname, two different directories get searched for a file name matching the theme. This is case sensitive on systems with case-sensitive filesystems. It's an error for a theme name to include path separators unless it's an absolute pathname.
The first directory is the themes subdirectory of your Ghostty configuration directory. That's $XDG_CONFIG_HOME/ghostty/themes or ~/.config/ghostty/themes.
The second directory is the themes subdirectory of the Ghostty resources directory. Ghostty ships with a multitude of themes that get installed into this directory. On macOS, this list is in the Ghostty.app/Contents/Resources/ghostty/themes directory. On Linux, this list is in the share/ghostty/themes directory (wherever you installed the Ghostty "share" directory).
To see a list of available themes, run ghostty +list-themes ⭐
A theme file is simply another Ghostty configuration file — same syntax, same configuration options. A theme can set any valid configuration option, so please do not use a theme file from an untrusted source 🙏 The built-in themes are audited to only set safe configuration options.
Some options cannot be set inside theme files, and the reason should be self-evident: a theme file cannot set theme or config-file. As of the time of writing, Ghostty won't show any warnings or errors if you set these in a theme file — they'll just be silently ignored 💀
Any additional colors specified via background, foreground, palette, etc. will override the colors from the theme.
To specify different themes for light and dark mode, use this syntax: light:theme-name,dark:theme-name. For example: light:Rose Pine Dawn,dark:Rose Pine. Whitespace around all values is trimmed and the order of light and dark doesn't matter. Both light and dark must be specified in this form. In this form, the theme used depends on your current desktop environment theme 🌗
There are some known bugs with light/dark mode theming, to be fixed in a future update:
- macOS:
<purple>titlebar tabs style is not updated when switching themes.
background— background color for the window. Specified as either hex (#RRGGBBorRRGGBB) or a named X11 color 🌈foreground— foreground color for the window. Specified as either hex (#RRGGBBorRRGGBB) or a named X11 color ✨background-image— background image for the terminal 🖼️
This should be a path to a PNG or JPEG file — other image formats are not yet supported.
The background image is currently per-terminal, not per-window. So if you're a heavy split user, the background image will be repeated across your splits. A future Ghostty improvement will address this.
WARNING: background images are currently duplicated in VRAM per-terminal. For sufficiently large images, this could lead to a large increase in memory usage (specifically VRAM usage). A future Ghostty improvement will resolve this by sharing image textures across terminals. 💀
Available since: 1.2.0
background-image-opacity— opacity of the background image 🎚️
This is relative to the value of background-opacity.
A value of 1.0 (the default) results in the background image sitting on top of the general background color, and then the combined result gets adjusted to the opacity specified by background-opacity.
A value less than 1.0 results in the background image being mixed with the general background color before the combined result is adjusted to the configured background-opacity.
A value greater than 1.0 gives the background image a higher opacity than the general background color. For example, if the configured background-opacity is 0.5 and background-image-opacity is set to 1.5, then the final opacity of the background image will be 0.5 * 1.5 = 0.75 🧮
Available since: 1.2.0
background-image-position— position of the background image 📍 Valid values are:top-lefttop-centertop-rightcenter-leftcentercenter-rightbottom-leftbottom-centerbottom-right
The default value is center.
Available since: 1.2.0
background-image-fit— how the background image fits. Valid values are:contain— preserving the aspect ratio, the background image scales to the largest size that can still be contained within the terminal, so the whole image stays visible 💖cover
cover— keeps the aspect ratio and scales the background image up to the smallest size that completely covers the terminal. Heads up though: this can clip one or more edges of the image at the terminal's edge 💅stretch— stretches the background image to the full size of the terminal, aspect ratio who? not preserved. it's giving chaos but it's your chaos 🫶none— literally don't scale the background image at all. leave it be. no thoughts, just pixels
The default value is contain.
Available since: 1.2.0
background-image-repeat— whether to repeat the background image or not, bestie.
If this is set to true, the background image gets repeated whenever there would otherwise be blank space hanging around it, because it doesn't completely fill the terminal area. ✨
The default value is false.
Available since: 1.2.0
selection-foreground— the foreground and background color for selection. If this isn't set, then the selection color is just the inverted window background and foreground — and note: not to be confused with the cell bg/fg, okay? don't do that to me 😭 Specified as either hex (#RRGGBBorRRGGBB) or a named X11 color. Since version 1.2.0, this can also be set tocell-foregroundto match the cell foreground color, orcell-backgroundto match the cell background color. glow up 💖selection-background— the other half of that pair, same rules, same vibes. both live in the same bullet up top so don't come for me 🎀selection-clear-on-typing— whether to clear selected text when you start typing. defaults totrue. this is typical behavior for most terminal emulators and text input fields, so like… it's the norm for a reason. If you set this tofalse, then the selected text will not be cleared when typing. iconic of you tbh.
"Typing" is specifically defined as any non-modifier (shift, control, alt, etc.) keypress that produces data to be sent to the application running within the terminal (e.g. the shell). Additionally, selection is cleared when any preedit or composition state is started (e.g. when typing languages such as Japanese). 🌸
If this is false, then the selection can still be manually cleared by clicking once or by pressing escape. your escape hatch stays 🦋
Available since: 1.2.0
selection-clear-on-copy— whether to clear selected text after copying. defaults tofalse.
When set to true, the selection is automatically cleared after any copy operation that invokes the copy_to_clipboard keyboard binding. Importantly — this will not clear the selection if the copy operation was invoked via copy-on-select. read that twice, bestie 👀
When set to false, the selection remains visible after copying, so you can actually see what you copied and potentially perform additional operations on the same selection. lowkey the superior experience fr fr.
selection-word-chars— the characters that mark word boundaries during text selection operations such as double-clicking. when you select a word, the selection stops at any of these characters. 💅
This is similar to the WORDCHARS environment variable in zsh, except this specifies the boundary characters rather than the word characters. the default includes common delimiters and punctuation that typically separate words in code and prose — iykyk.
Each character in this string becomes a word boundary. Multi-byte UTF-8 characters are supported, but only single codepoints can be specified. Multi-codepoint sequences (e.g. emoji) are not supported. sorry to the emoji girlies 😭
The null character (U+0000) is always treated as a boundary and does not need to be included in this configuration. one less thing 🫶
Default:
\t '"│`|:;,()[]{}<>$To add or remove specific characters, you can set this to a custom value. For example, to treat semicolons as part of words:
selection-word-chars = "\t '\"│`|:,()[]{}<>$"(see how the ; dipped out of there? that's the whole trick ✨)
Available since: 1.3.0
minimum-contrast— the minimum contrast ratio between the foreground and background colors. the ratio is a value between1and21. A value of1allows for no contrast at all (e.g. black on black — cursed but legal 💀). This value is the contrast ratio as defined by the WCAG 2.0 specification.
If you want to avoid invisible text (same color as background), a value of 1.1 is a good value. If you want to avoid text that is difficult to read, a value of 3 or higher is a good value. The higher the value, the more likely that text will become black or white. it's giving contrast enforcement era
This value does not apply to Emoji or images. they're exempt, they're special, they're the main characters 🌈
palette— the color palette for the 256 color form that many terminal applications use. The syntax of this configuration isN=COLORwhereNis0to255(for the 256 colors in the terminal color table) andCOLORis a typical RGB color code such as#AABBCCorAABBCC, or a named X11 color. For example,palette = 5=#BB78D9will set thepurplecolor. 💜
The palette index can be in decimal, binary, octal, or hexadecimal. Decimal is assumed unless a prefix is used: 0b for binary, 0o for octal, and 0x for hexadecimal. base nerd hours 🧚
For definitions on the color indices and what they canonically map to, see this cheat sheet.
For most themes, you only need to set the first 16 colors (0–15) since the rest of the palette (16–255) will be automatically generated by default (see palette-generate for more details). slay, less work for you 👑
palette-generate— whether to automatically generate the extended 256 color palette (indices16–255) from the base 16 ANSI colors. 🌈
This lets theme authors specify only the base 16 colors and have the rest of the palette be automatically generated in a consistent and aesthetic way. aesthetic is the operative word here.
When enabled, the 6×6×6 color cube and 24-step grayscale ramp are derived from interpolations of the base palette, giving a more cohesive look. Colors that have been explicitly set via palette are never overwritten. boundaries! 🫶
The default value is false (disabled), because many legacy programs using the 256-color palette hardcode assumptions about what these colors are (mostly assuming the xterm 256 color palette). However, this is still a very useful tool for theme authors and users who want to customize their palette without having to specify all 256 colors. ngl that's a lot of colors to type ✨
For more information on how the generation works, see here: https://gist.github.com/jake-stewart/0a8ea46159a7da2c808e5be2177e1783
Available since: 1.3.0
palette-harmonious— inverts the palette colors generated whenpalette-generateis enabled, so that the colors go in reverse order. 🔄 This allows palette-based applications to work well in both light and dark mode since the palettes are always relatively good colors. dual mode icon behavior
This defaults to off because some legacy terminal applications hardcode the assumption that palette indices 16–231 are ordered from darkest to lightest, so enabling this would make them unreadable. unreadable!! not cute. This is not a generally good assumption and we encourage modern terminal applications to use the indices in a more semantic way. 💅
This has no effect if palette-generate is disabled. (obvi)
For more information see palette-generate.
Available since: 1.3.0
cursor-color— the color of the cursor. If this is not set, a default will be chosen. ✨
Direct colors can be specified as either hex (#RRGGBB or RRGGBB) or a named X11 color.
Additionally, special values can be used to set the color to match other colors at runtime:
cell-foreground— match the cell foreground color. (Available since: 1.2.0)cell-background— match the cell background color. (Available since: 1.2.0)
cursor-opacity— the opacity level (opposite of transparency, keep up) of the cursor. A value of1is fully opaque and a value of0is fully transparent. A value less than0or greater than1will be clamped to the nearest valid value. Note that a sufficiently small value such as0.3may be effectively invisible and may make it difficult to find the cursor. 😭 bestie you will lose your cursor and you will not find it — consider yourself warned.cursor-style— the style of the cursor. This sets the default style. A running program can still request an explicit cursor style using escape sequences (such asCSI q). Shell configurations will often request specific cursor styles. 💅
Note that shell integration will automatically set the cursor to a bar at a prompt, regardless of this configuration. You can disable that behavior by specifying shell-integration-features = no-cursor or disabling shell integration entirely. the shell integration said "i'm the main character now"
Valid values are:
blockbarunderlineblock_hollow
cursor-style-blink— sets the default blinking state of the cursor. This is just the default state; running programs may override the cursor style using DECSCUSR (CSI q).
If this is not set, the cursor blinks by default. Note that this is not the same as a true value — as noted below. 🫶
If this is not set at all (null), then Ghostty will respect DEC Mode 12 (AT&T cursor blink) as an alternate approach to turning blinking on/off. If this is set to any value other than null, DEC mode 12 will be ignored but DECSCUSR will still be respected.
Valid values are:
- (blank)
truefalse
cursor-text— the color of the text under the cursor. If this is not set, a default will be chosen. Specified as either hex (#RRGGBBorRRGGBB) or a named X11 color. Since version 1.2.0, this can also be set tocell-foregroundto match the cell foreground color, orcell-backgroundto match the cell background color. 🎀cursor-click-to-move— enables the ability to move the cursor at prompts by clicking on a location in the prompt text. yup, click where you wanna type. mouse girlies rise 🦋
This feature requires prompt marking via OSC 133. Some shells like Fish (v4.1+) and Nu (0.111+) natively support this while others may require additional configuration or Ghostty's shell integration features to be enabled. 👑
Depending on the shell, this works either by translating your click position into a series of synthetic arrow key movements or by sending a click event directly to the shell. In either case, some unexpected behavior around edge cases is possible. edge cases are gonna edge case — just so you know, not a bug report waiting to happen 💀
mouse-hide-while-typing— hide the mouse the instant you start typing 👻
The mouse becomes visible again when the mouse is used (button, movement, etc.). Platform-specific behavior may dictate other scenarios where the mouse is shown. For example on macOS, the mouse is shown again when a new window, tab, or split is created.
scroll-to-bottom— controls when the surface gets scrolled all the way down ⬇️✨
The format of this is a list of options to enable separated by commas. If you prefix an option with no- then it is disabled. If you omit an option, its default value is used.
Available options:
keystroke— If set, scroll the surface to the bottom when the user presses a key that results in data being sent to the PTY (basically anything but modifiers or keybinds that are processed by Ghostty).output— If set, scroll the surface to the bottom if there is new data to display (e.g., when new lines are printed to the terminal).
The default is keystroke, no-output.
mouse-shift-capture— can running programs even see that you're holding shift while clicking? 🖱️
Typically, the shift key is used to extend mouse selection.
The default value of false means that the shift key is not sent with the mouse protocol and will extend the selection. This value can be conditionally overridden by the running program with the XTSHIFTESCAPE sequence.
The value true means that the shift key is sent with the mouse protocol but the running program can override this behavior with XTSHIFTESCAPE.
The value never is the same as false but the running program cannot override this behavior with XTSHIFTESCAPE. The value always is the same as true but the running program cannot override this behavior with XTSHIFTESCAPE.
If you always want shift to extend mouse selection even if the program requests otherwise, set this to never.
Valid values are:
truefalsealwaysnever
mouse-reporting— do apps get to hear about your mouse or not 🐭💬
Enable or disable mouse reporting. When set to false, mouse events will not be reported to terminal applications even if they request it. This allows you to always use the mouse for selection and other terminal UI interactions without applications capturing mouse input.
When set to true (the default), terminal applications can request mouse reporting and will receive mouse events according to their requested mode.
This can be toggled at runtime using the toggle_mouse_reporting keybind action.
mouse-scroll-multiplier— how fast the wheel spins the world 🎡
Multiplier for scrolling distance with the mouse wheel.
A prefix of precision: or discrete: can be used to set the multiplier only for scrolling with the specific type of devices. These can be comma-separated to set both types of multipliers at the same time, e.g. precision:0.1,discrete:3. If no prefix is used, the multiplier applies to all scrolling devices. Specifying a prefix was introduced in Ghostty 1.2.1.
The value will be clamped to [0.01, 10,000]. Both of these are extreme and you're likely to have a bad experience if you set either extreme.
The default value is "3" for discrete devices and "1" for precision devices.
background-opacity— the opacity level (opposite of transparency) of the background 🫧
A value of 1 is fully opaque and a value of 0 is fully transparent. A value less than 0 or greater than 1 will be clamped to the nearest valid value.
On macOS, background opacity is disabled when the terminal enters native fullscreen. This is because the background becomes gray and it can cause widgets to show through which isn't generally desirable.
On macOS, changing this configuration requires restarting Ghostty completely.
background-opacity-cells— should the opacity also apply to cells that have their own background color? 🎨
Normally, background-opacity is only applied to the window background. If a cell has an explicit background color set, such as red, then that background color will be fully opaque. An effect of this is that some terminal applications that repaint the background color of the terminal such as a Neovim and Tmux may not respect the background-opacity (by design).
Setting this to true will apply the background-opacity to all cells regardless of whether they have an explicit background color set or not.
Available since: 1.2.0
background-blur— whether to blur the background whenbackground-opacityis less than1🌫️
Valid values are:
- a nonnegative integer specifying the blur intensity
false, equivalent to a blur intensity of0true, equivalent to the default blur intensity of20, which is reasonable for a good looking blur. Higher blur intensities may cause strange rendering and performance issues.
On macOS 26.0 and later, there are additional special values that can be set to use the native macOS glass effects:
macos-glass-regular— Standard glass effect with some opacitymacos-glass-clear— Highly transparent glass effect
If the macOS values are set, then this implies background-blur = true on non-macOS platforms.
On Linux, the exact blur intensity is ignored and any positive integer or true value will enable background blur. On Wayland, Ghostty uses the ext-background-effect-v1 protocol to enable the blur effect, but this is not always supported on all compositors. Check the documentation of your compositor or desktop environment for blur support and how to configure it.
On X11, blur can only be enabled when using the KWin compositor as a part of KDE Plasma.
unfocused-split-opacity— the opacity level (opposite of transparency) of an unfocused split 😴
Unfocused splits by default are slightly faded out to make it easier to see which split is focused. To disable this feature, set this value to 1.
A value of 1 is fully opaque and a value of 0 is fully transparent. Because "0" is not useful (it makes the window look very weird), the minimum value is 0.15. This value still looks weird but you can at least see what's going on. A value outside of the range 0.15 to 1 will be clamped to the nearest valid value.
unfocused-split-fill— the color used to dim the unfocused split 🖌️
Unfocused splits are dimmed by rendering a semi-transparent rectangle over the split. This sets the color of that rectangle and can be used to carefully control the dimming effect.
This will default to the background color.
Specified as either hex (#RRGGBB or RRGGBB) or a named X11 color.
split-divider-color— the color of the split divider ✂️
If this is not set, a default will be chosen. Specified as either hex (#RRGGBB or RRGGBB) or a named X11 color.
Available since: 1.1.0
split-preserve-zoom— control when Ghostty preserves a zoomed split 🔍
Under normal circumstances, any operation that changes focus or layout of the split tree in a window will unzoom any zoomed split. This configuration allows you to control this behavior.
This can be set to navigation to preserve the zoomed split state when navigating to another split (e.g. via goto_split). This will change the zoomed split to the newly focused split instead of unzooming.
Any options can also be prefixed with no- to disable that option.
Example: split-preserve-zoom = navigation
Available since: 1.3.0
search-foreground,search-background— the foreground and background color for search matches 🍯
This only applies to non-focused search matches, also known as candidate matches.
Valid values:
- Hex (
#RRGGBBorRRGGBB) - Named X11 color
- "
cell-foreground" to match the cell foreground color - "
cell-background" to match the cell background color
The default value is black text on a golden yellow background.
search-selected-foreground,search-selected-background— the foreground and background color for the currently selected search match 🍑✨
This is the focused match that will be jumped to when using next/previous search navigation.
Valid values:
- Hex (
#RRGGBBorRRGGBB) - Named X11 color
- "
cell-foreground" to match the cell foreground color - "
cell-background" to match the cell background color
The default value is black text on a soft peach background.
command— the command to run, usually a shell 🐚
If this is not an absolute path, it'll be looked up in the PATH. If this is not set, a default will be looked up from your system. The rules for the default lookup are:
SHELLenvironment variable- passwd entry (user information)
This can contain additional arguments to run the command with. If additional arguments are provided, the command will be executed using /bin/sh -c to offload shell argument expansion.
To avoid shell expansion altogether, prefix the command with direct:, e.g. direct:nvim foo. This will avoid the roundtrip to /bin/sh but will also not support any shell parsing such as arguments with spaces, filepaths with ~, globs, etc. (Available since: 1.2.0)
You can also explicitly prefix the command with shell: to always wrap the command in a shell. This can be used to ensure our heuristics to choose the right mode are not used in case they are wrong. (Available since: 1.2.0)
This command will be used for all new terminal surfaces, i.e. new windows, tabs, etc. If you want to run a command only for the first terminal surface created when Ghostty starts, use the initial-command configuration.
That -e flag is basically the glow-up shortcut, and honestly? Iconic. For example: ghostty -e fish --with --custom --args. This flag sets the initial-command configuration, so peep that one for the full tea.
initial-command— lowkey the same ascommand, but it only applies to the very first terminal surface created when Ghostty starts. Any terminal surfaces after that one use thecommandconfig instead.
And bestie, listen: after that first terminal surface is created (or closed), there is no way to run this initial command again automatically. So yeah, setting it at runtime works, but it'll only affect the next terminal surface if that surface happens to be the first one ever created. Fr fr, that's the whole deal.
If you're using the ghostty CLI there's also a shortcut to set this with arguments directly: the -e flag. For example: ghostty -e fish --with --custom --args. The -e flag automatically forces some other behaviors too — not me casually changing your settings, it's for your own good:
- Disables shell expansion, since the input is expected to already be shell-expanded by the upstream (e.g. the shell you used to type in that
ghostty -ecommand). gtk-single-instance=false— this ensures a new instance is launched and the CLI args are actually respected.quit-after-last-window-closed=true— this ensures the Ghostty process exits when the command exits. Additionally, thequit-after-last-window-closed-delayis unset.shell-integration=detect(if notnone) — this prevents forcibly injecting any configured shell integration into the command's environment. With-eit's highly unlikely you're executing a shell, and forced shell integration is likely to cause problems (e.g. by wrapping your command in a shell, setting env vars, etc.). It's a safety measure to prevent unexpected behavior 💅. If you do want shell integration with a-e-executed command, you must either name your binary appropriately or source the shell integration script manually.
notify-on-command-finish— controls when command finished notifications get sent. Three options, choose your fighter:never— never send notifications (this is the default).unfocused— only send notifications if the surface that the command is running in is not focused.always— always send notifications.
Command finished notifications require that either shell integration is enabled, or that your shell sends OSC 133 escape sequences to mark the start and end of commands.
On GTK, there's a context menu item that will enable command finished notifications for a single command, overriding the never and unfocused options.
Available since 1.3.0.
notify-on-command-finish-action— if command finished notifications are enabled, this controls how the user is notified. The options:bell— enabled by defaultnotify— disabled by default
Options can be combined by listing them as a comma separated list, and options can be negated by prefixing them with no-. For example no-bell,notify. Slay.
Available since 1.3.0.
notify-on-command-finish-after— if command finished notifications are enabled, this controls how long a command must have been running before a notification will be sent. The default is five seconds.
The duration is specified as a series of numbers followed by time units. Whitespace is allowed between numbers and units. Each number and unit gets added together to form the total duration.
The allowed time units are as follows:
y— 365 SI days, or 8760 hours, or 31536000 seconds. No adjustments are made for leap years or leap seconds.d— one SI day, or 86400 seconds.h— one hour, or 3600 seconds.m— one minute, or 60 seconds.s— one second.ms— one millisecond, or 0.001 second.usorµs— one microsecond, or 0.000001 second.ns— one nanosecond, or 0.000000001 second.
Examples:
1h30m45s
Units can be repeated and will be added together, which means 1h1h is equivalent to 2h. This is confusing and should be avoided 🫠. A future update may disallow this.
The maximum value is 584y 49w 23h 34m 33s 709ms 551µs 615ns. Any value larger than this will be clamped to the maximum value.
Available since 1.3.0
env— extra environment variables to pass to commands launched in a terminal surface. The format isenv=KEY=VALUE.
env = foo=bar
env = bar=bazSetting env to an empty string resets the entire map to default (empty).
env =Setting a key to an empty string removes that particular key and corresponding value from the map.
env = foo=bar
env = foo=...will result in foo not being passed to the launched commands.
Setting a key multiple times overwrites previous entries.
env = foo=bar
env = foo=baz...will result in foo=baz being passed to the launched commands.
These environment variables override any existing environment variables set by Ghostty. So if you set GHOSTTY_RESOURCES_DIR, the value you set here overrides the value Ghostty typically automatically injects. Main character behavior honestly.
These environment variables will not be passed to commands run by Ghostty for other purposes, like open or xdg-open used to open URLs in your browser.
Available since: 1.2.0
input— data to send as input to the command on startup.
The configured command is launched using the typical rules, then the data specified as this input gets written to the pty before any other input can be provided.
The bytes are sent as-is with no additional encoding. Therefore, be cautious about input that can contain control characters, because this can be used to execute programs in a shell 😭. Like, genuinely, be careful.
The format of this value is:
raw:<string>— send raw text as-is. This uses Zig string literal syntax, so you can specify control characters and other standard escapes.path:<path>— read a filepath and send the contents. The path must be to a file with finite length, e.g. don't use a device such as/dev/stdinor/dev/urandomas these will block terminal startup indefinitely. Files are limited to 10MB in size to prevent excessive memory usage. If you have files larger than this, you should write a script to read the file and send it to the terminal.
If no valid prefix is found, it's assumed to be a raw: input. This is an ergonomic choice to allow you to simply write input = "Hello, world!" (a common case) without needing to prefix every value with raw:.
This can be repeated multiple times to send more data. The data is concatenated directly with no separator characters in between (e.g. no newline).
If any of the input sources do not exist, then none of the input will be sent. Input sources are not verified until the terminal is starting, so missing paths will not show up in config validation.
Changing this configuration at runtime will only affect new terminals.
Available since: 1.2.0
wait-after-command— iftrue, keep the terminal open after the command exits. Normally the terminal window closes when the running command (such as a shell) exits. With thistrue, the terminal window stays open until any keypress is received.
This is primarily useful for scripts or debugging.
abnormal-command-exit-runtime— the number of milliseconds of runtime below which we consider a process exit to be abnormal. This is used to show an error message when the process exits too quickly.
On Linux, this must be paired with a non-zero exit code. On macOS, we allow any exit code because of the way shell processes are launched via the login command.
scrollback-limit-bytes— the size of the scrollback buffer in bytes. This also includes the active screen. No matter what this is set to, enough memory will always be allocated for the visible screen, and anything leftover is the limit for the scrollback.
When this limit is reached, the oldest lines are removed from the scrollback.
Scrollback is stored in memory and allocated lazily up to this limit, so setting a very large limit does not immediately consume that amount of memory. On supported systems with scrollback compression enabled, Ghostty attempts to compress fully historical pages which are not currently visible while the terminal is idle. This can reduce physical memory usage, depending on the contents of the scrollback.
This limit always measures the uncompressed logical size of the terminal pages. Compression does not allow Ghostty to retain more history than the configured limit. Accessing compressed history restores it transparently and may increase the terminal's physical memory usage again.
This size is per terminal surface, not for the entire application.
A separate maximum can be set with scrollback-limit-lines; if both limits are set, then the first one reached will determine when scrollback is removed.
The default is 50 MB. Set this to unlimited to remove the byte limit.
This can be changed at runtime but will only affect new terminal surfaces.
scrollback-limit-lines— the maximum number of lines of scrollback to retain. This excludes the active screen. Soft-wrapped lines count as multiple lines.
This limit is an estimate. Internally, Ghostty will only trim lines up to the minimum allocation unit that is used internally (called a "page"). The size of a page depends on how many styles, graphemes, etc. take up the screen. In practice, this can be anywhere from a handful to a couple hundred lines. Importantly, memory is capped either way, so the actual limited lines will likely be slightly higher in practice. Ngl, it's giving "approximately accurate" and we love that for it 🎀
The default is unlimited, bestie. A separate cap can be set with scrollback-limit-bytes — and if you set both limits, whichever one gets reached first is the one that decides when scrollback gets yeeted. 💀
This can be changed at runtime, but it'll only affect new terminal surfaces (the existing ones are living their own truth).
scrollback-compression— whether to compress scrollback pages while the terminal is idle 🧚
Ghostty does its best to only compress when idle and decompress as needed. Which means compression doesn't lower IO throughput — no cap, it's giving efficiency. We recommend you keep it on, fr fr.
The scrollback limit stays an uncompressed logical limit no matter what this is set to, so turning compression off can bump up your physical memory usage but does not change how much history is retained.
Text-heavy terminal history generally compresses down to approximately 10% to 30% of its uncompressed page memory — that's a 70% to 90% reduction in physical memory for pages which are compressed. Compression savings are content-dependent, iykyk.
Note that the way Ghostty works is that we compress and discard the physical/resident memory but we retain virtual mappings. So you will not see a decrease in virtual memory usage, but you will see a decrease in physical/memory usage. 👑
Changing this at runtime affects future compression work. Pages which are already compressed remain compressed until their contents are accessed. Periodt.
scrollbar— control when the scrollbar is shown to scroll the scrollback buffer ✨
The default value is system.
Valid values:
system— respect the system settings for when to show scrollbars. On macOS, we only show scrollbars while actively scrolling or hovering the gutter. If the system setting is set to "Always", the scrollbar will be shown when the mouse is over the gutter area.never— never show a scrollbar. You can still scroll using the mouse, keybind actions, etc. but you will not have a visual UI widget showing a scrollbar. (Minimalist era 💅)
link— match a regular expression against the terminal text and associate clicking it with an action 🖱️
This can be used to match URLs, file paths, etc. Actions can be opening using the system opener (e.g. open or xdg-open) or executing any arbitrary binding action.
Links that are configured earlier take precedence over links that are configured later. Order matters, bestie.
A default link that matches a URL and opens it in the system opener always exists. This can be disabled using link-url.
TODO: This can't currently be set! 😭
link-url— enable URL matching 🌈
URLs are matched on hover with control (Linux) or command (macOS) pressed and open using the default system application for the linked URL.
The URL matcher is always lowest priority of any configured links (see link). If you want to customize URL matching, use link and disable this.
link-osc8— enable hyperlinks created with the OSC 8 escape sequence 🦋
When disabled, OSC 8 hyperlinks are not highlighted, previewed, copied, or opened.
This does not affect URL matching controlled by link-url.
Available since: 1.4.0
link-previews— show link previews for a matched URL 👀
When true, link previews are shown for all matched URLs. When false, link previews are never shown. When set to "osc8", link previews are only shown for hyperlinks created with the OSC 8 sequence (in this case, the link text can differ from the link destination).
Available since: 1.2.0
maximize— whether to start the window in a maximized state 🔥
This setting applies to new windows and does not apply to tabs, splits, etc. However, this setting will apply to all new windows, not just the first one.
Available since: 1.1.0
fullscreen— start new windows in fullscreen 🌸
This setting applies to new windows and does not apply to tabs, splits, etc. However, this setting will apply to all new windows, not just the first one.
Allowable values are:
false— don't start in fullscreen (default)true— start in native fullscreennon-native— (macOS only) start in non-native fullscreen, hiding the menu bar. This is faster than native fullscreen since it doesn't use animations. On non-macOS platforms, this behaves the same astrue.non-native-visible-menu— (macOS only) start in non-native fullscreen, keeping the menu bar visible. On non-macOS platforms, behaves liketrue.non-native-padded-notch— (macOS only) start in non-native fullscreen, hiding the menu bar but padding for the notch on applicable devices. On non-macOS platforms, behaves liketrue.
Important: tabs DO NOT WORK with non-native fullscreen modes. 😭 Non-native fullscreen removes the titlebar and macOS native tabs require the titlebar. If you use tabs, use true (native) instead.
On macOS, true (native fullscreen) does not work if window-decoration is set to false, because native fullscreen on macOS requires window decorations. The rules are the rules.
title— the title Ghostty will use for the window 🎀
This will force the title of the window to be this title at all times and Ghostty will ignore any set title escape sequences programs (such as Neovim) may send. Main character title energy only.
If you want a blank title, set this to one or more spaces by quoting the value. For example, title = " ". This effectively hides the title. This is necessary because setting a blank value resets the title to the default value of the running program. Sneaky but iconic.
This configuration can be reloaded at runtime. If it is set, the title will update for all windows. If it is unset, the next title change escape sequence will be honored but previous changes will not retroactively be set. This latter case may require you to restart programs such as Neovim to get the new title.
class— the setting that will change the application class value 💜
This controls the class field of the WM_CLASS X11 property (when running under X11), the Wayland application ID (when running under Wayland), and the bus name that Ghostty uses to connect to DBus.
Note that changing this value between invocations will create new, separate instances, of Ghostty when running with gtk-single-instance=true. See that option for more details.
Changing this value may break launching Ghostty from .desktop files, via DBus activation, or systemd user services as the system is expecting Ghostty to connect to DBus using the default class when it is launched. Be careful, bestie 🫶
The class name must follow the requirements defined in the GTK documentation.
The default is com.mitchellh.ghostty.
This only affects GTK builds.
x11-instance-name— this controls the instance name field of theWM_CLASSX11 property when running under X11 ⭐
It has no effect otherwise.
The default is ghostty.
This only affects GTK builds.
working-directory— the directory to change to after starting the command 📁
This setting is secondary to the window-inherit-working-directory setting. If a previous Ghostty terminal exists in the same process, window-inherit-working-directory will take precedence. Otherwise, this setting will be used. Typically, this setting is used only for the first window.
The default is inherit except in special scenarios listed next. On macOS, if Ghostty can detect it is launched from launchd (double-clicked) or open, then it defaults to home. On Linux with GTK, if Ghostty can detect it was launched from a desktop launcher, then it defaults to home.
The value of this must be an absolute path, a path prefixed with ~/ (the tilde will be expanded to the user's home directory), or one of the special values below:
home— the home directory of the executing user.inherit— the working directory of the launching process.
keybind— key bindings, aka the whole personality of your terminal ⌨️✨
The format is trigger=action. Duplicate triggers will overwrite previously set values. The list of actions is available in the documentation or using the ghostty +list-actions command.
Trigger: +-separated list of keys and modifiers. Example: ctrl+a, ctrl+shift+b, up.
If the key is a single Unicode codepoint, the trigger will match any presses that produce that codepoint. These are impacted by keyboard layouts. For example, a will match the a key on a QWERTY keyboard, but will match the q key on a AZERTY keyboard (assuming US physical layout).
For Unicode codepoints, matching is done by comparing the set of modifiers with the unmodified codepoint. The unmodified codepoint is sometimes called an "unshifted character" in other software, but all modifiers are considered, not only shift. For example, ctrl+a will match a but not ctrl+shift+a (which is A on a US keyboard).
Further, codepoint matching is case-insensitive and the unmodified codepoint is always case folded for comparison. As a result, ctrl+A configured will match when ctrl+a is pressed. Note that this means some key combinations are impossible depending on keyboard layout. For example, ctrl+_ is impossible on a US keyboard because _ is shift+- and ctrl+shift+- is not equal to ctrl+_ (because the modifiers don't match!). More details on impossible key combinations can be found at this excellent source written by Qt developers: https://doc.qt.io/qt-6/qkeysequence.html#keyboard-layout-issues 💀
Physical key codes can be specified by using any of the key codes as specified by the W3C specification. For example, KeyA will match the physical a key on a US standard keyboard regardless of the keyboard layout. These are case-sensitive. No cap. 👑
Okay so for aesthetic reasons, the w3c codes also support snake case 💅. For example, key_a is equivalent to KeyA. The only exceptions are function keys, e.g. F1 is f1 (no underscore). This is a consequence of our internal code using snake case, but it’s purposely supported and tested so it is safe to use. It allows an all-lowercase binding which the original author finds aesthetically pleasing — and honestly? lowercase binds are lowkey a vibe ✨.
Function keys such as insert, up, f5, etc. are also specified using the keys as specified by the previously linked W3C specification 🎀.
Physical keys always match with a higher priority than Unicode codepoints, so if you specify both a and KeyA, the physical key will always be used regardless of what order they are configured. No cap 🫶.
The special key catch_all can be used to match any key that is not otherwise bound. This can be combined with modifiers — for example ctrl+catch_all will match any key pressed with ctrl that is not otherwise bound. When looking up a binding, Ghostty first tries to match catch_all with modifiers. If no match is found and the event has modifiers, it falls back to catch_all without modifiers. It’s giving “catch everything else” energy 🌈.
Valid modifiers are shift, ctrl (alias: control), alt (alias: opt, option), and super (alias: cmd, command). You may use the modifier or the alias. When debugging keybinds, the non-aliased modifier will always be used in output 👑.
Note: The fn or “globe” key on keyboards are not supported as a modifier. This is a limitation of the operating systems and GUI toolkits that Ghostty uses. 💀
Some additional notes for triggers:
- modifiers cannot repeat,
ctrl+ctrl+ais invalid. - modifiers and keys can be in any order,
shift+a+ctrlis weird, but valid. - only a single key input is allowed,
ctrl+a+bis invalid.
You may also specify multiple triggers separated by > to require a sequence of triggers to activate the action. For example, ctrl+a>n=new_window will only trigger the new_window action if the user presses ctrl+a followed separately by n. In other software, this is sometimes called a leader key, a key chord, a key table, etc. There is no hardcoded limit on the number of parts in a sequence. Literally go off 🧚.
⚠️ Warning: If you define a sequence as a CLI argument toghostty, you probably have to quote the keybind since>is a special character in most shells. Example:ghostty –keybind=`ctrl+a>n=new_window'
A trigger sequence has some special handling:
- Ghostty will wait an indefinite amount of time for the next key in the sequence. There is no way to specify a timeout. The only way to force the output of a prefix key is to assign another keybind to specifically output that key (e.g.
ctrl+a>ctrl+a=text:foo) or press an unbound key which will send both keys to the program. - If an unbound key is pressed during a sequence and a
catch_allbinding exists that would ignore the input, the entire sequence is dropped and nothing happens. Otherwise, the entire sequence is encoded and sent to the running program as if no keybind existed. - If a prefix in a sequence is previously bound, the sequence will override the previous binding. For example, if
ctrl+ais bound tonew_windowandctrl+a>nis bound tonew_tab, pressingctrl+awill do nothing. - Adding to the above, if a previously bound sequence prefix is used in a new, non-sequence binding, the entire previously bound sequence will be unbound. For example, if you bind
ctrl+a>nandctrl+a>t, and then bindctrl+adirectly, bothctrl+a>nandctrl+a>twill become unbound. - Trigger sequences are not allowed for
global:orall:-prefixed triggers. This is a limitation we could remove in the future.
Action is the action to take when the trigger is satisfied. It takes the format action or action:param. The latter form is only valid if the action requires a parameter. Bestie, this is the main character of the keybind line 💖.
ignore— Do nothing, ignore the key input. This can be used to black hole certain inputs to have no effect.unbind— Remove the binding. This makes it so the previous action is removed, and the key will be sent through to the child command if it is printable. Unbind will remove any matching trigger, includingphysical:-prefixed triggers without specifying the prefix.csi:text— Send a CSI sequence. e.g.csi:Asends “cursor up”.esc:text— Send an escape sequence. e.g.esc:ddeletes to the end of the word to the right.text:text— Send a string. Uses Zig string literal syntax. e.g.text:\x15sendsCtrl-U.- All other actions can be found in the documentation or by using the
ghostty +list-actionscommand.
Some notes for the action:
- The parameter is taken as-is after the
:. Double quotes or other mechanisms are included and NOT parsed. If you want to send a string value that includes spaces, wrap the entire trigger/action in double quotes. Example:--keybind="up=csi:A B"
There are some additional special values that can be specified for keybind:
keybind=clearwill clear all set keybindings.
⚠️ Warning: keybind=clear removes ALL keybindings up to this point, including the default keybindings. Not me finding out the hard way 😭.
The keybind trigger can be prefixed with some special values to change the behavior of the keybind. These are:
all:— Make the keybind apply to all terminal surfaces. By default, keybinds only apply to the focused terminal surface. If this is true, then the keybind will be sent to all terminal surfaces. This only applies to actions that are surface-specific. For actions that are already global (e.g.quit), this prefix has no effect.- Available since:
1.0.0
- Available since:
global:— Make the keybind global. By default, keybinds only work within Ghostty and under the right conditions (application focused, sometimes terminal focused, etc.). If you want a keybind to work globally across your system (e.g. even when Ghostty is not focused), specify this prefix. This prefix impliesall:.- Note: this does not work in all environments; see the additional notes below for more information.
- Available since:
1.0.0on macOS,1.2.0on GTK
unconsumed:— Do not consume the input. By default, a keybind will consume the input, meaning that the associated encoding (if any) will not be sent to the running program in the terminal. If you wish to send the encoded value to the program, specify theunconsumed:prefix before the entire keybind. For example:unconsumed:ctrl+a=reload_config.global:andall:-prefixed keybinds will always consume the input regardless of this setting. Since they are not associated with a specific terminal surface, they’re never encoded.- Available since:
1.0.0
- Available since:
performable:— Only consume the input if the action is able to be performed. For example, thecopy_to_clipboardaction will only consume the input if there is a selection to copy. If there is no selection, Ghostty behaves as if the keybind was not set. This has no effect withglobal:orall:-prefixed keybinds. For key sequences, this will reset the sequence if the action is not performable (acting identically to not having a keybind set at all).- Performable keybinds will not appear as menu shortcuts in the application menu. This is because the menu shortcuts force the action to be performed regardless of the state of the terminal. Performable keybinds will still work, they just won’t appear as a shortcut label in the menu.
- Available since:
1.1.0
Keybind triggers are not unique per prefix combination. For example, ctrl+a and global:ctrl+a are not two separate keybinds. The keybind set later will overwrite the keybind set earlier. In this case, the global: keybind will be used. Periodt 👑.
Multiple prefixes can be specified. For example, global:unconsumed:ctrl+a=reload_config will make the keybind global and not consume the input to reload the config. Multiple prefix stacking is iconic, honestly 🎀.
On macOS, this feature requires accessibility permissions to be granted to Ghostty. When a global: keybind is specified and Ghostty is launched or reloaded, Ghostty will attempt to request these permissions. If the permissions are not granted, the keybind will not work. On macOS, you can find these permissions in System Preferences -> Privacy & Security -> Accessibility. Go grant them, bestie 🫶.
Since Ghostty 1.4.0, global shortcuts on Linux are primarily supported through the vicinae-hotkey-v1 protocol, available out-of-the-box with the following Wayland compositors and desktop environments:
- Hyprland since version
0.56.0
On X11 or when your Wayland compositor/desktop environment does not support vicinae-hotkey-v1, the much more widely-used XDG Global Shortcuts protocol is used instead. Slay for fallbacks ✨.
Note: XDG Global Shortcuts rely on a functional XDG Desktop Portal implementation that is designed to be used with your desktop environment or compositor. Please make sure that you have the correct one installed.
Desktop environments that are known to support the XDG Global Shortcuts protocol include:
- KDE Plasma since
5.27withxdg-desktop-portal-kdeinstalled - GNOME since
48withxdg-desktop-portal-gnomeinstalled - Hyprland before version
0.56.0, withxdg-desktop-portal-hyprlandinstalled. Some manual configuration is required. Consult the steps outlined on the Hyprland Wiki to set up D-Bus-based global shortcuts correctly.
Desktop environments and compositors that don’t implement either protocol do not support global shortcuts, like wlroots-based compositors e.g. Sway (see upstream issue) and COSMIC. 💀
✨ Chained Actions ✨
Okay bestie, this is where it gets good. A single keybind can trigger multiple actions — you just use the chain keyword for every action after the first one. When the keybind fires, all the chained actions run in order. The syntax is giving:
keybind = ctrl+a=new_window
keybind = chain=goto_split:leftSo that binds ctrl+a to first open a new window, then move focus to the left split. Iconic, honestly. Every chain entry just appends an action onto the most recently defined keybind — and you can chain as many as your heart desires:
keybind = ctrl+a=new_window
keybind = chain=goto_split:left
keybind = chain=toggle_fullscreenHeads up though: chained actions cannot have prefixes likeglobal:orunconsumed:. The flags from the original keybind apply to the entire chain, periodt.
Chained actions also work with key sequences, like:
keybind = ctrl+a>n=new_window
keybind = chain=goto_split:leftWhen you're chaining onto a key sequence, the chain applies to the most recent binding in the sequence — iykyk.
Chained keybinds are available since Ghostty 1.3.0. 🎀
✨ Key Tables ✨
You can also create a named set of keybindings, which is called a “key table.” A key table has to be explicitly activated before its bindings become available — that's the whole vibe. This is how you'd implement stuff like a “copy mode”, “vim mode”, etc. Basically: modal keyboard input, bestie. 🦋
Key tables are defined with the syntax <table>/<binding>. The <binding> value is literally everything documented above for keybinds. The <table> value is the name of the key table. Table names can contain anything except /, =, +, and > — and that's because + and > are reserved for keybind syntax (modifier combinations and key sequences, respectively). So like, foo/ctrl+a=new_window defines a binding inside a table named foo.
Tables get activated and deactivated using the binding actions activate_key_table:<name> and deactivate_key_table. There are other table-related binding actions too — go check the documentation for the full list. These are the primary way you interact with key tables.
Binding lookup proceeds from the innermost table outward, which means keybinds in the default table stay available unless you explicitly unbind them in an inner table. Slay.
A key table has some special syntax and handling, and you're gonna wanna know these:
<name>/(with no binding at all) defines and clears a table, resetting all of its keybinds and settings. Fresh start energy.- You cannot activate a table that is already the innermost table — those attempts are just ignored. However, the same table can appear multiple times in the stack as long as it's not innermost (e.g.,
A -> B -> A -> Bis valid, butA -> B -> Bis not). Don't ask, it's the rules. - A table can be activated in one-shot mode using
activate_key_table_once:<name>. A one-shot table is automatically deactivated when any non-catch-all binding is invoked. One and done. 💅 - Key sequences work within tables:
foo/ctrl+a>ctrl+b=new_window. If an invalid key gets pressed, the sequence ends but the table remains active. - Chain actions work within tables too — the
chainkeyword applies to the most recently defined binding in the table. e.g. if you settable/ctrl+a=new_windowyou can chain it up by usingchain=text:hello. Important:chainitself doesn't get prefixed with the table name, because it applies to the most recent binding in any table. - Prefixes like
global:work within tables:foo/global:ctrl+a=new_window. 🫶
Key tables are available since Ghostty 1.3.0.
💅 key-remap
Remap modifier keys within Ghostty. This lets you swap or reassign modifier keys at the application level without touching your system-wide settings. No cap, it's that clean.
The format is from=to where both from and to are modifier key names. You can use generic names like ctrl, alt, shift, super (on macOS: cmd/command) or sided names like left_ctrl, right_alt, etc.
Okay so important caveat, bestie: this will NOT change keyboard layout or key encodings outside of Ghostty. For example, on macOS,option+amay still produceåeven ifoptionis remapped toctrl. Desktop environments usually handle key layout long before Ghostty ever receives the key events. Not our department. 😭
Example:
key-remap = ctrl=super
key-remap = left_control=right_altImportant notes, and please read these fr fr:
- This is a one-way remap. If you remap
ctrl=super, then the physical Ctrl key acts as Super, but the Super key remains Super. It's not a swap, it's a glow-up for one key only. - Remaps are not transitive. If you remap
ctrl=superandalt=ctrl, pressing Alt will produce Ctrl, NOT Super. The chain does not continue. - This affects both keybind matching and terminal input encoding. It does NOT impact keyboard layout or how keys are interpreted prior to Ghostty receiving them. For example,
option+aon macOS may still produceåeven ifoptionis remapped toctrl. - Generic modifiers (e.g.
ctrl) match both left and right physical keys. Use sided names (e.g.left_ctrl) to remap only one side. 🎯
There are other edge case scenarios that may not behave as expected but are working as intended the way this feature is designed:
- On macOS, bindings in the main menu will trigger before any remapping is done. This is because macOS itself handles menu activation and it happens before Ghostty receives the key event. To work around this, you should unbind the menu items and rebind them using your desired modifier.
This configuration can be repeated to specify multiple remaps. Stack 'em up. 🌸
🎀 window-padding-x
Horizontal window padding, bestie. This is the padding between the terminal cells and the left and right window borders. The value is in points, meaning it gets scaled appropriately for screen DPI. ✨
If this value is set too large, the screen will render nothing, because the grid will be completely squished by the padding. It's up to you as the user to pick a reasonable value. If you pick an unreasonable value, a warning will appear in the logs. Consider this your vibe check. 💀
Changing this configuration at runtime will only affect new terminals, i.e. new windows, tabs, etc.
To set a different left and right padding, specify two numerical values separated by a comma. For example, window-padding-x = 2,4 will set the left padding to 2 and the right padding to 4. If you want both paddings to be the same value, just use a single value — for example, window-padding-x = 2 sets both paddings to 2. Simple as.
🌈 window-padding-y
Vertical window padding, the y-axis twin of the above. This applies padding between the terminal cells and the top and bottom window borders. The value is in points, meaning it will be scaled appropriately for screen DPI.
Same warning, same energy: if this value is set too large, the screen will render nothing, because the grid will be completely squished by the padding. It's up to you as the user to pick a reasonable value. If you pick an unreasonable value, a warning will appear in the logs.
Changing this configuration at runtime will only affect new terminals, i.e. new windows, tabs, etc.
To set a different top and bottom padding, specify two numerical values separated by a comma. For example, window-padding-y = 2,4 sets the top padding to 2 and the bottom padding to 4. If you want both paddings to be the same, use a single value — for example, window-padding-y = 2 sets both paddings to 2. 🫶
🦋 window-padding-balance
Okay so the viewport dimensions are usually not perfectly divisible by the cell size. In that case, some extra padding on the end of a column and the bottom of the final row may exist. If this is true, then that extra padding gets automatically balanced between all four edges to minimize imbalance on one side. If this is false, the top left grid cell will always hug the edge with zero padding — other than what may be specified with the other window-padding options.
If other window-padding fields are set and this is true, this will still apply. The other padding is applied first and may affect how many grid cells actually exist, and this is applied last in order to balance the padding given a certain viewport size and grid cell size. Order matters, bestie.
Valid values are:
false— No balancing is applied.true— Balance the padding, but cap the top padding to avoid excessive space above the first row. Any excess is shifted to the bottom.equal— Balance the padding equally on all sides without any top-padding cap. (Available since:1.4.0) 👑
💜 window-padding-color
The color of the padding area of the window. Valid values are:
background— The background color specified inbackground.extend— Extend the background color of the nearest grid cell.extend-always— Same as “extend” but always extends without applying any of the heuristics that disable extending noted below.
The “extend” value will be disabled in certain scenarios. On primary screen applications (e.g. not something like Neovim), the color will not be extended vertically if any of the following are true:
- The nearest row has any cells that have the default background color. The thinking is that in this case, the default background color looks fine as a padding color. ✨
- The nearest row is a prompt row (requires shell integration). The thinking here is that prompts often contain powerline glyphs that do not look good extended.
- The nearest row contains a perfect fit powerline character. These don't look good extended.
So like, the heuristics are just out here protecting you from ugly padding. Respect. 🙈
🔥 window-vsync
Synchronize rendering with the screen refresh rate. If true, this will minimize tearing and align redraws with the screen, but may cause input latency. If false, this will maximize redraw frequency but may cause tearing, and under heavy load may use more CPU and power.
This defaults to true because out-of-sync rendering on macOS can cause kernel panics (macOS 14.4+) and performance issues for external displays over some hardware such as DisplayLink. Yeah, kernel panics. Not a drill. 🫠 If you want to minimize input latency, set this to false — with the known aforementioned risks, bestie.
Changing this value at runtime will only affect new terminals.
This setting is only supported currently on macOS.
window-inherit-working-directory— set this totrueand every new window inherits the working directory of the previously focused window. 🫶 If nothing was focused before, it falls back to the default working directory instead (that's theworking-directoryoption, iykyk).tab-inherit-working-directory— same deal but for tabs:truemeans new tabs inherit the working directory of the previously focused tab. No previously focused tab? Default working directory, brought to you by theworking-directoryoption. ✨split-inherit-working-directory— and for split panes:truemeans new splits inherit the working directory of the previously focused split. If no split was previously focused, you get the default working directory (theworking-directoryoption, again, she's everywhere 💅).
window-inherit-font-size— iftrue, new windows and tabs inherit the font size of the previously focused window. If no window was previously focused, the default font size gets used. If this isfalse, then the default font size specified in the configfont-sizeis what you get. No in-between, bestie. 🎀
window-decoration— this is your preference for window decorations, and I cannot stress "preference" enough: the actual OS, desktop environment, window manager, etc. can override it. Ghostty will do its best to respect it, but sometimes it's just not possible. 😭
Valid values:
none— all window decorations are disabled. No titlebar, no borders, none of it. On macOS this also disables tabs (the system enforces that one). 💀auto— automatically picks client-side or server-side decorations based on what the current OS and desktop environment say they prefer. This one usually makes Ghostty look the most "native" on your desktop. 👑client— prefer client-side decorations. Available since: 1.1.0server— prefer server-side decorations. This is only relevant on Linux with GTK, either on X11 or on Wayland with a compositor that supports theorg_kde_kwin_server_decorationprotocol (e.g. KDE Plasma, but almost any non-GNOME desktop supports this protocol). Ifserveris set but the environment doesn't support server-side decorations, client-side decorations get used instead. Available since: 1.1.0
The default value is auto.
For backwards compatibility and convenience, this setting also accepts boolean true and false values. true is equivalent to auto, and false is equivalent to none. Super handy if you live primarily on systems that don't differentiate between client and server-side decorations (e.g. macOS and Windows).
The toggle_window_decorations keybind action can be used to make a keybinding that toggles this setting at runtime. 🔥
macOS: to hide the titlebar without removing the native window borders or rounded corners, use macos-titlebar-style = hidden instead. Noted.
window-title-font-family— the font used for the application's window and tab titles. If you leave it unset, the system default font is used. Note: any font available on the system is fair game — this one does not have to be a fixed-width font. 🌸 Available since: 1.0.0 on macOS, 1.1.0 on GTKwindow-subtitle— the text shown in the subtitle of the window. Valid values:false— disable the subtitle. 🙈working-directory— set the subtitle to the working directory of the surface. 🦋
This feature is only supported on GTK. Available since: 1.1.0
window-theme— the theme used for the windows. Valid values:auto— figure out the theme from the configured terminal background color. This has no effect if thethemeconfiguration has separate light and dark themes; in that case,autobehaves exactly likesystem. 🧚system— use the system theme.light— use the light theme, no matter what the system theme is.dark— use the dark theme, no matter what the system theme is. 💜ghostty— use the background and foreground colors specified in your Ghostty configuration. Only supported on Linux builds. 🐧
On macOS, if macos-titlebar-style is tabs or transparent, the window theme is automatically set based on the luminosity of the terminal background color. That only applies to terminal windows, though — this setting still applies to non-terminal windows inside Ghostty.
Currently only supported on macOS and Linux.
window-colorspace— the color space used when interpreting terminal colors. "Terminal colors" means colors you specified in your config and colors produced by direct-color SGR sequences. 🌈
Valid values:
srgb— interpret colors in the sRGB color space. This is the default. ⭐display-p3— interpret colors in the Display P3 color space.
This setting is currently only supported on macOS.
window-height— the initial window size. By default this size is in terminal grid cells, and both values must be set to take effect — if only one value is set, it gets ignored, sorry bestie. 😭
We don't currently support specifying a size in pixels, but a future change can enable that. If this isn't specified, the app runtime picks some default size.
Note that the window manager may put limits on the size or straight-up override it — a tiling window manager might force the window to a certain size to fit the grid, for example. There's nothing Ghostty can do about that, but it will make an effort. 💅
Sizes larger than the screen size get clamped to the screen size, which you can totally use to make a maximized-by-default window. 👑
This will not affect new tabs, splits, or other nested terminal elements — it only affects the initial window size of any new window. Changing this value won't change the size of a window that already exists; it's only read for the initial size.
BUG: on Linux with GTK, the calculated window size won't properly account for window decorations, so the grid dimensions won't exactly match this configuration. If window decorations are disabled (see window-decoration), it works as expected. 🫠
Windows smaller than 10 wide by 4 high are not allowed. Periodt.
window-width— the width half of thewindow-heightsituation; same grid-cell situation, same both-values-or-nothing rule. ⭐
window-position-x— the starting window position, in pixels, relative to the top-left corner of the primary monitor. Both values must be set for this to take effect — one alone gets ignored. 🙈
Note that the window manager may limit or override the position (tiling WMs, I'm looking at you — they may force a position to fit the grid). Nothing Ghostty can do, but it'll make an effort.
Also note that negative values are up to the OS and window manager too — some WMs simply won't allow windows to be placed off-screen.
Invalid positions are runtime-specific, but generally they get clamped to the nearest valid position.
On macOS, the window position is relative to the top-left corner of the visible screen area — so if the menu bar is showing, your window lands below the menu bar. 🍎
Note: this is only supported on macOS. The GTK runtime doesn't support setting the window position, since windows are only allowed to position themselves in X11 and not Wayland. 💀
window-position-y— the y half of the position pair. Same rules bestie, it's a matching set. ✨
window-save-state— whether to save and restore window state. And "window state" means position, size, tabs, splits, etc. Some of that state requires shell integration, like preserving working directories — seeshell-integrationfor more. 🐚
Three valid values:
default— use the default system behavior. On macOS, this only saves state if the app is forcibly terminated or if it's configured systemwide via Settings.app. 🍓never— never ever save window state.always— always save window state whenever Ghostty exits. 🔥
If you change this to never while Ghostty isn't running, the next launch will NOT restore the window state.
If you change this to default while Ghostty isn't running and the previous exit saved state, the next launch will still restore the window state — because Ghostty can't know whether that previous exit was a forced save or not (macOS doesn't give it that info).
If you change this value so that state gets saved while Ghostty isn't running, the previous window state will not be restored, because Ghostty only saves state on exit if this is enabled.
The default value is default.
Currently only supported on macOS — on Linux this has no effect. 🫶
window-step-resize— resize the window in discrete increments of the focused surface's cell size. If this is disabled, surfaces resize in pixel increments. Currently only supported on macOS. 🎀window-new-tab-position— where new tabs get created. Valid values:current— insert the new tab after the currently focused tab, or at the end if there are no focused tabs. 🌸end— insert the new tab at the end of the tab list. ⭐
window-show-tab-bar— whether to show the tab bar. Valid values:always— always display the tab bar, even when there's only one tab. Available since: 1.2.0auto(default)
Automatically show and hide the tab bar. The tab bar is only shown when there are two or more tabs present. Cute, right? ✨
never— never show the tab bar. Tabs are only accessible via the tab overview or by keybind actions.
Currently only supported on Linux (GTK). 🐧
window-titlebar-background— background color for the window titlebar. This only takes effect ifwindow-themeis set toghostty. Currently only supported in the GTK app runtime. Specified as either hex (#RRGGBBorRRGGBB) or a named X11 color. 🎨window-titlebar-foreground— foreground color for the window titlebar. This only takes effect ifwindow-themeis set toghostty. Currently only supported in the GTK app runtime. Specified as either hex (#RRGGBBorRRGGBB) or a named X11 color. 🎨drag-handle— controls when drag handles are shown over splits, allowing splits to be rearranged with mouse controls. Valid values:always— always display the drag handle, even when there’s only one split. 💅auto(default) — automatically show and hide the drag handle. On Linux, the handle is only shown when there are two or more splits present. On macOS, the handle is only hidden when there’s one split in fullscreen mode, otherwise it’s shown when hovered. 🍎never— never show the drag handle. Splits then cannot be rearranged with mouse controls. 🙈 Available since:1.4.0.
resize-overlay— this controls when resize overlays are shown. Resize overlays are a transient popup that shows the size of the terminal while the surfaces are being resized. The possible options are:always— always show resize overlays.never— never show resize overlays.after-first— the resize overlay will not appear when the surface is first created, but will show up if the surface is subsequently resized. The default isafter-first.
resize-overlay-position— if resize overlays are enabled, this controls the position of the overlay. The possible options are:centertop-lefttop-centertop-rightbottom-leftbottom-centerbottom-rightThe default iscenter.
resize-overlay-duration— if resize overlays are enabled, this controls how long the overlay is visible on the screen before it is hidden. The default is ¾ of a second or750 ms. ⏱️
The duration is specified as a series of numbers followed by time units. Whitespace is allowed between numbers and units. Each number and unit will be added together to form the total duration.
The allowed time units are as follows:
y— 365 SI days, or 8760 hours, or 31536000 seconds. No adjustments are made for leap years or leap seconds.d— one SI day, or 86400 seconds.h— one hour, or 3600 seconds.m— one minute, or 60 seconds.s— one second.ms— one millisecond, or 0.001 second.usorµs— one microsecond, or 0.000001 second.ns— one nanosecond, or 0.000000001 second.
Examples:
1h30m45s
Units can be repeated and will be added together. This means that 1h1h is equivalent to 2h. This is confusing and should be avoided. A future update may disallow this. 😭
The maximum value is 584y 49w 23h 34m 33s 709ms 551µs 615ns. Any value larger than this will be clamped to the maximum value.
Available since 1.0.0.
focus-follows-mouse— iftrue, when there are multiple split panes, the mouse selects the pane that is focused. This only applies to the currently focused window; e.g. mousing over a split in an unfocused window will not focus that split and bring the window to front. Default isfalse. 🖱️clipboard-read— whether to allow programs running in the terminal to read/write to the system clipboard (OSC 52, for googling). The default is to allow clipboard reading after prompting the user and allow writing unconditionally. Valid values are:askallowdeny
clipboard-write— the source gives this one no description text, just the option name, so we’re not making anything up 💅clipboard-write-limit-bytes— the maximum size in bytes of a single clipboard write by a program running in the terminal via the Kitty clipboard protocol (OSC 5522). This doesn’t apply toOSC 52, which is limited by the maximum length of an escape sequence hardcoded into Ghostty for now.
Data beyond the limit fails the entire write with an EFBIG status, discards the transaction, and leaves the clipboard untouched. Later write-related packets are ignored until a new write begins.
The data is buffered in memory while the write is in progress, so this limit bounds how much memory a program can make Ghostty allocate per write. A future improvement will attempt to spool large writes to disk.
The default is 64 MiB, the minimum a conforming implementation must accept. Set this to unlimited to remove the limit, allowing writes bounded only by available memory. A value of 0 rejects every non-empty write. To reject clipboard writes entirely, use clipboard-write = deny instead.
This can be changed at runtime and applies to writes that begin after the change.
Available since: 1.4.0.
clipboard-trim-trailing-spaces— trims trailing whitespace on data that is copied to the clipboard. This does not affect data sent to the clipboard viaclipboard-write. This only applies to trailing whitespace on lines that have other characters. Completely blank lines always have their whitespace trimmed. ✂️clipboard-paste-protection— require confirmation before pasting text that appears unsafe. This helps prevent a “copy/paste attack” where a user may accidentally execute unsafe commands by pasting text with newlines or carriage returns. 🚨clipboard-paste-bracketed-safe— iftrue, bracketed pastes will be considered safe. By default, bracketed pastes are considered safe. “Bracketed” pastes are pastes while the running program has bracketed paste mode enabled (a setting set by the running program, not the terminal emulator). 🫶title-report— turns title reporting on or off (CSI 21 t). This escape sequence allows the running program to query the terminal title. This is a common security issue and is disabled by default.
Warning: This can expose sensitive information at best and enable arbitrary code execution at worst (with a maliciously crafted title and a minor amount of user interaction).
Available since: 1.0.1.
image-storage-limit— the total amount of bytes that can be used for image data (e.g. the Kitty image protocol) per terminal screen. The maximum value is4,294,967,295(4GiB). The default is320MB. If this is set to zero, then all image protocols will be disabled. This value is separate for primary and alternate screens so the effective limit per surface is double. 🖼️copy-on-select— whether to automatically copy selected text to the clipboard. Valid values:none— do not copy selected text automatically.primary— on Linux, copy to the selection clipboard only. This has no effect on macOS. (Available since:1.4.0)clipboard— copy text to the system clipboard only.both— copy to both clipboards on Linux, and only the system clipboard on macOS. (Available since:1.4.0) For backward compatibility and convenience, a value oftrueis the same asprimaryon Linux andclipboardon macOS, andfalseis an alias fornone. The default value isprimaryon Linux andnoneotherwise. 🫶
right-click-action— the action to take when the user right-clicks on the terminal surface. Valid values:context-menu— show the context menu.paste— paste the contents of the clipboard.copy— copy the selected text to the clipboard.copy-or-paste— if there is a selection, copy the selected text to the clipboard; otherwise, paste the contents of the clipboard.ignore— do nothing, ignore the right-click. The default value iscontext-menu.
middle-click-action— the action to take when the user middle-clicks on the terminal surface. Valid values:primary-paste— paste from the selection clipboard on Linux. Does nothing on macOS.clipboard-paste— paste from the system clipboard.ignore— do nothing, ignore the middle click. The default value isprimary-paste.
click-repeat-interval— the time in milliseconds between clicks to consider a click a repeat (double, triple, etc.) or an entirely new single click. A value of zero will use a platform-specific default. The default on macOS is determined by the OS settings. On every other platform it is500ms. 🖱️config-file— additional configuration files to read. This configuration can be repeated to read multiple configuration files. Configuration files themselves can load more configuration files. Paths are relative to the file containing theconfig-filedirective. For command-line arguments, paths are relative to the current working directory.
Prepend a ? character to the file path to suppress errors if the file does not exist. If you want to include a file that begins with a literal ? character, surround the file path in double quotes (").
Cycles are not allowed. If a cycle is detected, an error will be logged and the configuration file will be ignored. 🔁🚫
Configuration files get loaded after the configuration they're defined inside of, in the order they're defined. THIS IS A VERY SUBTLE BUT IMPORTANT POINT. Bestie, let me say it another way: config files don't actually take effect until the entire configuration has been loaded. So like, look at this:
config-file = "foo"
a = 1If foo contains a = 2, then the final value of a is gonna be 2, because foo is loaded after the config file that set up the nested config-file value. Order matters, periodt. 💅
config-default-files— when this is true, the default configuration file paths get loaded. The default configuration file paths are currently only the XDG config path ($XDG_CONFIG_HOME/ghostty/config.ghostty).
If this is false, the default configuration paths will not be loaded. This is targeted directly at using Ghostty from the CLI in a way that minimizes external effects.
This one is a CLI-only configuration. Setting it in a configuration file will have no effect. It's not an error, but it literally will not do anything. This configuration can only be set via CLI arguments.
confirm-close-surface— this one confirms that a surface should be closed before closing it. 🫶
It defaults to true. If you set it to false, surfaces will close with zero confirmation whatsoever. You can also set it to always, which will always confirm closing a surface, even if shell integration says a process isn't running.
quit-after-last-window-closed— whether or not to quit after the last surface is closed.
This defaults to false on macOS since that's standard behavior for a macOS application. On Linux, it defaults to true since that's generally expected behavior.
On Linux, if this is true, Ghostty can delay quitting fully until a configurable amount of time has passed after the last window is closed. See the documentation of quit-after-last-window-closed-delay. 💖
quit-after-last-window-closed-delay— controls how long Ghostty will stay running after the last open surface has been closed. This only has an effect ifquit-after-last-window-closedis also set totrue.
The minimum value for this configuration is 1s. Any values lower than this will be clamped to 1s. 🚨
The duration is specified as a series of numbers followed by time units. Whitespace is allowed between numbers and units. Each number and unit will be added together to form the total duration.
The allowed time units are as follows:
y— 365 SI days, or 8760 hours, or 31536000 seconds. No adjustments are made for leap years or leap seconds.d— one SI day, or 86400 seconds.h— one hour, or 3600 seconds.m— one minute, or 60 seconds.s— one second.ms— one millisecond, or 0.001 second.usorµs— one microsecond, or 0.000001 second.ns— one nanosecond, or 0.000000001 second. Examples:1h30m45s
Units can be repeated and will be added together. This means 1h1h is equivalent to 2h. This is confusing and should be avoided. A future update may disallow this. 🙈
The maximum value is 584y 49w 23h 34m 33s 709ms 551µs 615ns. Any value larger than this will be clamped to the maximum value.
By default quit-after-last-window-closed-delay is unset and Ghostty will quit immediately after the last window is closed if quit-after-last-window-closed is true.
Only implemented on Linux.
initial-window— this controls whether an initial window is created when Ghostty is run. Note that ifquit-after-last-window-closedis true andquit-after-last-window-closed-delayis set, settinginitial-windowtofalsewill mean Ghostty will quit after the configured delay if no window is ever created. Only implemented on Linux and macOS.undo-timeout— the duration that undo operations remain available. After this time, the operation gets removed from the undo stack and can't be undone. 😭
The default value is 5 seconds.
This timeout applies per operation, meaning that if you perform multiple operations, each operation gets its own timeout. New operations do not reset the timeout of previous operations.
A timeout of zero will effectively disable undo operations. It's not possible to set an infinite timeout, but you can set a very large timeout to effectively disable the timeout (on the order of years). This is highly discouraged, because it will cause the undo stack to grow indefinitely, memory usage to grow unbounded, and terminal sessions to never actually quit. 💀
The duration is specified as a series of numbers followed by time units. Whitespace is allowed between numbers and units. Each number and unit will be added together to form the total duration.
The allowed time units are as follows:
y— 365 SI days, or 8760 hours, or 31536000 seconds. No adjustments are made for leap years or leap seconds.d— one SI day, or 86400 seconds.h— one hour, or 3600 seconds.m— one minute, or 60 seconds.s— one second.ms— one millisecond, or 0.001 second.usorµs— one microsecond, or 0.000001 second.ns— one nanosecond, or 0.000000001 second. Examples:1h30m45s
Units can be repeated and will be added together. This means 1h1h is equivalent to 2h. This is confusing and should be avoided. A future update may disallow this. 🌀
This configuration is only supported on macOS. Linux doesn't support undo operations at all, so this configuration has no effect.
Available since: 1.2.0
quick-terminal-position— the position of the "quick" terminal window. To learn more about the quick terminal, see the documentation for thetoggle_quick_terminalbinding action. 👑
Valid values are:
top— Terminal appears at the top of the screen.bottom— Terminal appears at the bottom of the screen.left— Terminal appears at the left of the screen.right— Terminal appears at the right of the screen.center— Terminal appears at the center of the screen.
On macOS, changing this configuration requires restarting Ghostty completely. 💅
Note: There is no default keybind for toggling the quick terminal. To enable this feature, bind the toggle_quick_terminal action to a key.
quick-terminal-size— the size of the quick terminal.
The size can be specified either as a percentage of the screen dimensions (height/width), or as an absolute size in pixels. Percentage values are suffixed with % (e.g. 20%) while pixel values are suffixed with px (e.g. 300px). A bare value without a suffix is a config error. 🚨
When only one size is specified, the size parameter affects the size of the quick terminal on its primary axis, which depends on its position: height for quick terminals placed on the top or bottom, and width for left or right. The primary axis of a centered quick terminal depends on the monitor's orientation: height when on a landscape monitor, and width when on a portrait monitor. 🖥️
The secondary axis would be maximized for non-center positioned quick terminals unless another size parameter is specified, separated from the first by a comma (,). Percentage and pixel sizes can be mixed together: for instance, a size of 50%,500px for a top-positioned quick terminal would be half a screen tall, and 500 pixels wide.
Available since: 1.2.0
gtk-quick-terminal-layer— the layer of the quick terminal window. The higher the layer, the more windows the quick terminal may conceal. ✨
Valid values are:
overlay
The quick terminal appears in front of all windows.
top(default)
The quick terminal appears in front of normal windows but behind fullscreen overlays like lock screens.
bottom
The quick terminal appears behind normal windows but in front of wallpapers and other windows in the background layer.
background
The quick terminal appears behind all windows.
GTK Wayland only.
Available since: 1.2.0
gtk-quick-terminal-namespace— the namespace for the quick terminal window.
This is an identifier that's used by the Wayland compositor and/or scripts to determine the type of layer surfaces and to possibly apply unique effects. 🦋
GTK Wayland only.
Available since: 1.2.0
quick-terminal-screen— the screen where the quick terminal should show up.
Valid values are:
main— The screen that the operating system recommends as the main screen. On macOS, this is the screen that is currently receiving keyboard input. This screen is defined by the operating system and not chosen by Ghostty.mouse— The screen that the mouse is currently hovered over. 🖱️macos-menu-bar— The screen that contains the macOS menu bar as set in the display settings on macOS. This is a bit confusing because every screen on macOS has a menu bar, but this is the screen that contains the primary menu bar.
The default value is main because this is the recommended screen by the operating system.
On macOS, macos-menu-bar uses the screen containing the menu bar. On Linux/Wayland, macos-menu-bar is treated as equivalent to main.
Note: On Linux, there is no universal concept of a "primary" monitor. Ghostty uses the compositor-reported primary output when available and falls back to the first monitor reported by GDK if no primary output can be resolved. 🌈
quick-terminal-animation-duration— duration (in seconds) of the quick terminal enter and exit animation. Set it to0to disable animation completely. This can be changed at runtime. 🎀
Only implemented on macOS. iykyk 💅
quick-terminal-autohide— bestie, this one auto-hides the quick terminal the second focus wanders off to another window. Set it tofalseand the quick terminal stays open even when it loses focus, like the main character it is ✨
Defaults to true on macOS and false on Linux/BSD. Why the split? Because global shortcuts on Linux need system configuration and are considerably less accessible than on macOS, so it's way more preferable to keep the quick terminal open until the user has finished their task. This default may change in the future (no cap, they said it themselves).
quick-terminal-space-behavior— this one picks how the quick terminal behaves when you switch between macOS spaces. And yes, macOS spaces are just virtual desktops that you can manually create or that get automatically created when an app is in full-screen mode 🦋
Valid values are:
move— when you switch to another space, the quick terminal also moves to the current space. It follows you, loyal icon 🫶remain— the quick terminal stays only in the space where it was originally opened and will not follow when you switch to another space.
The default value is move.
Only implemented on macOS. On Linux the behavior is always equivalent to move.
Available since: 1.1.0
quick-terminal-keyboard-interactivity— determines under which circumstances the quick terminal should receive keyboard input. Peep the corresponding Wayland documentation for a way more detailed explanation of each option's behavior 👑
[!NOTE] The exact behavior of each option may differ significantly across compositors — experiment with them on your system to find one that suits your liking! fr fr 🙈
Valid values are:
none— the quick terminal will not receive any keyboard input. ghosted 💀on-demand(default) — the quick terminal would only receive keyboard input when it is focused.exclusive— the quick terminal will always receive keyboard input, even when another window is currently focused. bold. iconic.
Only has an effect on Linux Wayland. On macOS the behavior is always equivalent to on-demand.
Available since: 1.2.0
shell-integration— whether to enable shell integration auto-injection or not. And bestie, shell integration greatly enhances the terminal experience by enabling a number of features 🌸- Working directory reporting so new tabs and splits inherit the previous terminal's working directory.
- Prompt marking that enables the “jump_to_prompt” keybinding.
- If you're sitting at a prompt, closing a terminal will not ask for confirmation.
- Resizing the window with a complex prompt usually paints way better.
Allowable values are:
none— do not do any automatic injection. You can still manually configure your shell to enable the integration.detect— detect the shell based on the filename.bash,elvish,fish,nushell,zsh— use this specific shell injection scheme.
The default value is detect.
shell-integration-features— which shell integration features to enable. These require our shell integration to be loaded, either automatically viashell-integrationor manually, okurrr 💜
The format of this is a list of features to enable separated by commas. If you prefix a feature with no- then it is disabled. If you omit a feature, its default value is used, so you must explicitly disable features you don't want. You can also use true or false to turn all features on or off.
Example: cursor, no-cursor, sudo, no-sudo, title, no-title
Available features:
cursor— set the cursor to a bar at the prompt.sudo— set sudo wrapper to preserve terminfo.title— set the window title via shell integration.ssh-env— enable SSH environment variable compatibility. Automatically convertsTERMfromxterm-ghosttytoxterm-256colorwhen connecting to remote hosts and propagatesCOLORTERM,TERM_PROGRAM, andTERM_PROGRAM_VERSION. Whether or not these variables will be accepted by the remote host(s) will depend on whether or not the variables are allowed in theirsshd_config. (Available since: 1.2.0)ssh-terminfo— enable automatic terminfo installation on remote hosts. Attempts to install Ghostty's embedded terminfo entry usingticon local cache misses. Requiresticto be available on remote hosts. Successful installations are cached locally to avoid repeat installations. If desired, the+ssh-cacheCLI action can be used to manage the installation cache manually using various arguments. (Available since: 1.2.0)path— add Ghostty's binary directory toPATH. This ensures theghosttycommand is available in the shell even if shell init scripts resetPATH. This is particularly useful on macOS wherePATHis often overridden by system scripts. The directory is only added if not already present.
SSH features work independently and can be combined for optimal experience: when both ssh-env and ssh-terminfo are enabled, Ghostty will install its terminfo on remote hosts and use xterm-ghostty as TERM, falling back to xterm-256color with environment variables if terminfo installation fails. team work makes the dream work 🧚
command-palette-entry— custom entries into the command palette. so you can put your lil faves in there 💅
Each entry requires the title, the corresponding action, and an optional description. Each field should be prefixed with the field name, a colon (:), and then the specified value. The syntax for actions is identical to the one for keybind actions. Whitespace in between fields is ignored.
If you need to embed commas or any other special characters in the values, enclose the value in double quotes and it will be interpreted as a Zig string literal. This is also useful for including whitespace at the beginning or the end of a value. See the Zig documentation for more information on string literals. Note that multiline string literals are not supported.
Double quotes can not be used around the field names. rude but okay 🙄
command-palette-entry = title:Reset Font Style, action:csi:0m
command-palette-entry = title:Crash on Main Thread,description:Causes a crash on the main (UI) thread.,action:crash:main
command-palette-entry = title:Focus Split: Right,description:"Focus the split to the right, if it exists.",action:goto_split:right
command-palette-entry = title:"Ghostty",description:"Add a little Ghostty to your terminal.",action:"text:\xf0\x9f\x91\xbb"There are some additional special values that can be specified for command-palette-entry:
command-palette-entry=clearwill clear all command entries. > Warning: this removes ALL entries up to this point, including the default entries. Available since: 1.4.0 😭
By default, the command palette is preloaded with most actions that might be useful in an interactive setting yet do not have easily accessible or memorizable shortcuts. The default entries can be restored by setting this setting to an empty value:
command-palette-entry =Available since: 1.2.0
osc-color-report-format— sets the reporting format for OSC sequences that request color information. Ghostty currently supports OSC 10 (foreground), OSC 11 (background), and OSC 4 (256 color palette) queries, and by default the reported values are scaled-up RGB values, where each component are 16 bits. That's how most terminals report these values, periodt. However, some legacy applications may require 8-bit, unscaled, components. We also support turning off reporting altogether. The components are lowercase hex values. 🌈
Allowable values are:
none— OSC 4/10/11 queries receive no reply. silence. 💀8-bit— color components are return unscaled, e.g.rr/gg/bb16-bit— color components are returned scaled, e.g.rrrr/gggg/bbbb
The default value is 16-bit.
vt-kam-allowed— iftrue, allows the “KAM” mode (ANSI mode 2) to be used within the terminal. KAM disables keyboard input at the request of the application. This is not a common feature and is not recommended to be enabled 🫣 This will not be documented further because if you know you need KAM, you know. If you don't know if you need KAM, you don't need it. iykyk, literally.vt-window-resize-allowed— iftrue, allows the running program to resize the window using the xtermCSI 8 ; rows ; columns tescape sequence. If a parameter is zero or omitted, the current size of that dimension is kept. Sizes smaller than 40 columns by 10 rows are raised to that size so that a program can't shrink the window to hide its output. sneaky sneaky 🕵️
The request is ignored if the terminal is in a split, in a window with multiple tabs, or the quick terminal, or if the window manager controls the window size, such as when it is fullscreen, maximized, or tiled. Sizes larger than the screen are clamped to the screen.
This is disabled by default because it lets any program, including one running on a remote machine, change the size of your window. yeah no thank you 🚩
Available since: 1.4.0
vt-xt-checksum-report— enables or disables checksum reporting (DECRQCRA,CSI Pi ; Pg ; Pt ; Pl ; Pb ; Pr * y). This escape sequence allows the running program to ask for a checksum of an area of the screen. Terminal test suites use it to check what is on the screen.
This is disabled by default because a program can ask for the checksum of one cell at a time and so read back everything on the screen, including the output of other programs 🚨
While this is disabled, XTCHECKSUM (CSI Ps # y), which changes how the checksum is calculated, is ignored as well.
Available since: 1.4.0
vt-xt-checksum-extension
Okay so this one controls how the checksum for DECRQCRA gets calculated (peep vt-xt-checksum-report for the deets on that). This is the calculation that's in effect after a reset, just like xterm's checksumExtension resource. A running program can swap it out with XTCHECKSUM (CSI Ps # y) and it'll stay that way until the next reset. Default? The calculation of a real DEC terminal, obviously. 💅
Valid values are:
negate— report the negated sum, exactly like DEC terminals do.attributes— add bold, underline, blink, inverse, invisible, and protected attributes to the value of each cell.trim— omit plain spaces, except for the first cell of the area.undrawn— count cells that were never written to as spaces instead of skipping them.full— use the full codepoint of each cell instead of the DEC 8-bit value.
Prefix a value with no- to disable it. For example, esctest expects no-negate,no-attributes,no-trim,full when run with --xterm-checksum, which is xterm's checksumExtension: 23. Slay, consistency. ✨
The bits of xterm's resource are described in its man page and its control sequence documentation, but where those disagree with xterm's implementation, Ghostty follows the implementation. The docs describe bit 3 as omitting cells that were never written to, but xterm skips those cells by default and counts them as spaces with the bit set — which is undrawn here. It also lists a bit 5 that xterm doesn't even implement. 💀 The way documentation lies sometimes, smh.
Available since: 1.4.0
custom-shader
Custom shaders to run after the default shaders. This is a file path to a GLSL-syntax shader, for all platforms. 🎨
Warning: Invalid shaders can cause Ghostty to become unusable, such as by causing the window to be completely black. If this happens, you can unset this configuration to disable the shader. No cap, read this twice. 😭
Custom shader support is based on and compatible with Shadertoy shaders. Shaders should specify a mainImage function, and the available uniforms largely match Shadertoy, with some caveats and Ghostty-specific extensions.
The uniform values available to shaders are as follows:
sampler2D iChannel0— input texture.
A texture containing the current terminal screen. If multiple custom shaders are specified, the output of previous shaders is written to this texture, to allow combining multiple effects. 🌀
vec3 iResolution— output texture size,[width, height, 1](in px).float iTime— time in seconds since first frame was rendered.float iTimeDelta— time in seconds since previous frame was rendered.float iFrameRate— average framerate. (NOT CURRENTLY SUPPORTED)int iFrame— number of frames that have been rendered so far.float iChannelTime[4]— current time for video or sound input. (N/A)vec3 iChannelResolution[4]— resolutions of the 4 input samplers.
Currently only iChannel0 exists, and iChannelResolution[0] is identical to iResolution.
vec4 iMouse— mouse input info. (NOT CURRENTLY SUPPORTED)vec4 iDate— date/time info. (NOT CURRENTLY SUPPORTED)float iSampleRate— sample rate for audio. (N/A)
Ghostty-specific extensions:
vec4 iCurrentCursor— info about the terminal cursor.iCurrentCursor.xyis the-X,+Ycorner of the current cursor.iCurrentCursor.zwis the width and height of the current cursor.
vec4 iPreviousCursor— info about the previous terminal cursor.vec4 iCurrentCursorColor— color of the terminal cursor.vec4 iPreviousCursorColor— color of the previous terminal cursor.vec4 iCurrentCursorStyle— style of the terminal cursor
Macros simplified use are defined for the various cursor styles:
CURSORSTYLE_BLOCKor0CURSORSTYLE_BLOCK_HOLLOWor1CURSORSTYLE_BARor2CURSORSTYLE_UNDERLINEor3CURSORSTYLE_LOCKor4
vec4 iPreviousCursorStyle— style of the previous terminal cursorvec4 iCursorVisible— visibility of the terminal cursor.float iTimeCursorChange— timestamp of terminal cursor change.
When the terminal cursor changes position or color, this is set to the same time as the iTime uniform, allowing you to compute the time since the change by subtracting this from iTime.
float iTimeFocus— timestamp when the surface last gainediFocus.
When the surface gains focus, this is set to the current value of iTime, similar to how iTimeCursorChange works. This allows you to compute the time since focus was gained or lost by calculating iTime - iTimeFocus. Use this to create animations that restart when the terminal regains focus. 🦋
int iFocus— current focus state of the surface.
Set to 1.0 when the surface is focused, 0.0 when unfocused. This allows shaders to detect unfocused state and avoid animation artifacts from large time deltas caused by infrequent "deceptive frames" (e.g., modifier key presses, link hover events in unfocused split panes). Check iFocus > 0 to determine if the surface is currently focused.
vec3 iPalette[256]— the 256-color terminal palette.
RGB values for all 256 colors in the terminal palette, normalized to [0.0, 1.0]. Index 0-15 are the ANSI colors, 16-231 are the 6x6x6 color cube, and 232-255 are the grayscale colors. 🌈
vec3 iBackgroundColor— terminal background color (RGB).vec3 iForegroundColor— terminal foreground color (RGB).vec3 iCursorColor— terminal cursor color (RGB).vec3 iCursorText— terminal cursor text color (RGB).vec3 iSelectionBackgroundColor— selection background color (RGB).vec3 iSelectionForegroundColor— selection foreground color (RGB).
If the shader fails to compile, the shader will be ignored. Any errors related to shader compilation will not show up as configuration errors and only show up in the log, since shader compilation happens after configuration loading on the dedicated render thread. For interactive development, use shadertoy.com. 👑 (log-only errors are such a vibe check fail but okay.)
This can be repeated multiple times to load multiple shaders. The shaders will be run in the order they are specified.
This can be changed at runtime and will affect all open terminals.
custom-shader-animation
If true (default), the focused terminal surface will run an animation loop when custom shaders are used. This uses slightly more CPU (generally less than 10%) but allows the shader to animate. This only runs if there are custom shaders and the terminal is focused. 🎀
If this is set to false, the terminal and custom shader will only render when the terminal is updated. This is more efficient but the shader will not animate. (Trade-off city.)
This can also be set to always, which will always run the animation loop regardless of whether the terminal is focused or not. The animation loop will still only run when custom shaders are used. Note that this will use more CPU per terminal surface and can become quite expensive depending on the shader and your terminal usage. ⚠️ Bestie, always goes hard on your battery.
This can be changed at runtime and will affect all open terminals.
bell-features
Bell features to enable if bell support is available in your runtime. Not all features are available on all runtimes. The format of this is a list of features to enable separated by commas. If you prefix a feature with no- then it is disabled. If you omit a feature, its default value is used.
Valid values are:
system
Instruct the system to notify the user using built-in system functions. This could result in an audiovisual effect, a notification, or something else entirely. Changing these effects require altering system settings: for instance under the "Sound > Alert Sound" setting in GNOME, or the "Accessibility > System Bell" settings in KDE Plasma. 🖥️
On macOS, this plays the system alert sound.
audio
Play a custom sound. (Available since 1.3.0 on macOS)
attention(enabled by default)
Request the user's attention when Ghostty is unfocused, until it has received focus again. On macOS, this will bounce the app icon in the dock once. On Linux, the behavior depends on the desktop environment and/or the window manager/compositor:
- On KDE, the background of the desktop icon in the task bar would be highlighted;
- On GNOME, you may receive a notification that, when clicked, would bring the Ghostty window into focus;
- On Sway, the window may be decorated with a distinctly colored border;
- On other systems this may have no effect at all.
title(enabled by default)
Prepend a bell emoji (🔔) to the title of the alerted surface until the terminal is re-focused or interacted with (such as on keyboard input). 🔔✨
border
Display a border around the alerted surface until the terminal is re-focused or interacted with (such as on keyboard input). 🖼️
Available since: 1.2.0 on GTK, 1.2.1 on macOS
Example: audio, no-audio, system, no-system
Available since: 1.2.0
bell-audio-path
If audio is an enabled bell feature, this is a path to an audio file. If the path is not absolute, it is considered relative to the directory of the configuration file that it is referenced from, or from the current working directory if this is used as a CLI flag. The path may be prefixed with ~/ to reference the user's home directory. 🎵
Available since: 1.2.0 on GTK, 1.3.0 on macOS.
bell-audio-volume
So if audio is one of your enabled bell features, this is literally the volume slider for it 💖 — the volume the audio file plays at, measured relative to your system volume.
It's a floating point number that goes from 0.0 (total silence, shhh 🤫) all the way up to 1.0 (as loud as possible, rip your ears off 🔥). The default is 0.5.
Available since:1.2.0on GTK,1.3.0on macOS. ✨
app-notifications
This one controls the in-app notifications Ghostty shows you 🎀.
On Linux (GTK), in-app notifications show up as toasts 🍞. Toasts appear overlaid on top of the terminal window. They're used to show info that isn't critical but may be important — like, not an emergency, but lowkey you should know.
The possible notifications are:
clipboard-copy(default:true) — shows a notification when text gets copied to the clipboard 📋config-reload(default:true) — shows a notification when the configuration is reloaded 🔄
To enable a notification, just specify its name. To disable one, prefix the name with no- 🙈. Example: to disable clipboard-copy, set this configuration to no-clipboard-copy. To enable it, set this configuration to clipboard-copy.
You can do multiples at once — just separate them with a comma. Periodt.
Also (important!):
- A value of
falsewill disable all notifications. - A value of
truewill enable all notifications.
This configuration only applies to GTK, bestie — macOS girlies, this one's not for you 💅.
Available since: 1.1.0
macos-non-native-fullscreen
If this is anything other than false, fullscreen mode on macOS won't use the native fullscreen — instead it makes the window fullscreen without animations and uses a new space 🌌. It's faster than the native fullscreen mode since it doesn't use animations, so like, speed ✨.
Important: tabs DO NOT WORK in this mode 💀. Non-native fullscreen removes the titlebar, and macOS native tabs require the titlebar. If you use tabs, you should not use this mode. Consider this your official warning.
And if you do fullscreen a window with tabs anyway? The currently focused tab will become fullscreen while the others remain in a separate window in the background 🫠. You can switch to that window using normal window-switching keybindings such as command+tilde. When you exit fullscreen, the window will return to the tabbed state it was in before — so it does recover, ngl.
Allowable values are:
true— use non-native macOS fullscreen, hide the menu barfalse— use native macOS fullscreenvisible-menu— use non-native macOS fullscreen, keep the menu bar visiblepadded-notch— use non-native macOS fullscreen, hide the menu bar, but ensure the window is not obscured by the notch on applicable devices. The area around the notch will remain transparent currently, but in the future we may fill it with the window background color 🌈
Changing this option at runtime works, but will only apply to the next time the window is made fullscreen 🙃. If a window is already fullscreen, it will retain the previous setting until fullscreen is exited.
macos-window-buttons
Whether the window buttons in the macOS titlebar are visible 👀. You know the ones — the colored buttons in the upper left corner of most macOS apps, aka the traffic lights 🚦, that let you close, miniaturize, and zoom the window.
Heads up: this setting has no effect when window-decoration = none or macos-titlebar-style = hidden, because the window buttons are always hidden in these modes. Can't show what's already gone 💅.
Valid values are:
visible— show the window buttonshidden— hide the window buttons
The default value is visible.
Changing this option at runtime only applies to new windows.
Available since: 1.2.0
macos-titlebar-style
The style of the macOS titlebar 🎀. Available values are: native, transparent, tabs, and hidden. Let's get into it:
The native style uses the native macOS titlebar with zero customization. The titlebar will match your window theme (see window-theme).
The transparent style is the same as native but the titlebar will be transparent and allow your window background color to come through ✨. This makes a more seamless window appearance but looks a little less typical for a macOS application and may not work well with all themes.
The transparent style will also update in real-time to dynamic changes to the window background color — e.g. via OSC 11. To make this more aesthetically pleasing, this only happens if the terminal is a window, tab, or split that borders the top of the window 🪟. This avoids a disjointed appearance where the titlebar color changes but all the topmost terminals don't match. Iconic attention to detail tbh.
The tabs style is a completely custom titlebar that integrates the tab bar into the titlebar. This titlebar always matches the background color of the terminal. There are some limitations to this style: on macOS 13 and below, saved window state will not restore tabs correctly 🫠. macOS 14 does not have this issue and any other macOS version has not been tested.
The hidden style hides the titlebar. Unlike window-decoration = none, however, it does not remove the frame from the window or cause it to have squared corners. Changing to or from this option at run-time may affect existing windows in buggy ways 💀 — you've been warned.
When hidden, the top titlebar area can no longer be used for dragging the window. To drag the window, you can use option+click on the resizable areas of the frame to drag the window. This is a standard macOS behavior and not something Ghostty enables — it's just the OS doing its thing.
The default value is transparent. This is an opinionated choice but it's one I think is the most aesthetically pleasing and works in most cases 💅👑
Changing this option at runtime only applies to new windows.
macos-titlebar-proxy-icon
Whether the proxy icon in the macOS titlebar is visible 🗂️. The proxy icon is the icon that represents the folder of your current working directory — you can see this very clearly in the macOS built-in Terminal.app titlebar.
The proxy icon is only visible with the native macOS titlebar style.
Valid values are:
visible— show the proxy iconhidden— hide the proxy icon
The default value is visible.
This setting can be changed at runtime and will affect all currently open windows, but only after their working directory changes again 😭. So to make this work after changing the setting, you must usually cd to a different directory, open a different file in an editor, etc. Annoying but that's the vibe.
macos-dock-drop-behavior
Controls the windowing behavior when you drop a file or folder onto the Ghostty icon in the macOS dock 📁✨.
Valid values are:
new-tab— create a new tab in the current window, or open a new window if none existnew-window— create a new window unconditionally
The default value is new-tab.
This setting is only supported on macOS and has no effect on other platforms 💅.
macos-option-as-alt
Okay so macOS doesn't have a distinct "alt" key and instead has the "option" key, which behaves slightly differently 😩. On macOS by default, the option key plus a character will sometimes produce a Unicode character. For example, on US standard layouts option-b produces ∫. Cute, but this may be undesirable if you want to use "option" as an "alt" key for keybindings in terminal programs or shells.
This configuration lets you change the behavior so that option is treated as alt 🦋.
The default behavior (unset) will depend on your active keyboard layout. If your keyboard layout is one of the keyboard layouts listed below, then the default value is true. Otherwise, the default value is false. Keyboard layouts with a default value of true are:
- U.S. Standard
- U.S. International
Note that if an Option-sequence doesn't produce a printable character, it will be treated as Alt regardless of this setting (e.g. alt+ctrl+a). So some things just work no matter what 🫶.
Explicit values that can be set:
If true, the Option key will be treated as Alt. This makes terminal sequences expecting Alt to work properly, but will break Unicode input sequences on macOS if you use them via the Alt key 💔.
You may set this to false to restore the macOS Alt key unicode sequences, but this will break terminal sequences expecting Alt to work. Pick your fighter, bestie.
The values left or right enable this for the left or right Option key, respectively 👈👉.
macos-window-shadow
Whether to enable the macOS window shadow 🌫️. The default value is true. With some window managers and window transparency settings, you may find false more visually appealing — a little aesthetic tweak if the shadow's giving too much, y'know?
macos-hidden
If true, the macOS icon in the dock and app switcher will be hidden 🙈. This is mainly intended for those primarily using the quick-terminal mode.
Note that setting this to true means that keyboard layout changes will no longer be automatic 😭.
Control whether the macOS app is excluded from the dock and app switcher — a "hidden" state. This is mainly intended for those primarily using quick-terminal mode, but is a general configuration for any use case.
Available values:
never— the macOS app is never hiddenalways— the macOS app is always hidden
Note: when the macOS application is hidden, keyboard layout changes will no longer be automatic. This is a limitation of macOS 💀 — nothing Ghostty can do about it.
Available since: 1.2.0
macos-auto-secure-input
If true, Ghostty on macOS will automatically enable the "Secure Input" feature when it detects that a password prompt is being displayed 🔒👑
"Secure Input" is a macOS security feature that prevents applications from reading keyboard events 🛡️. This can always be enabled manually using the Ghostty > Secure Keyboard Entry menu item.
Okay real talk before we move on: automatic password prompt detection is heuristics-based, bestie. It might not always work like you expect. Specifically, it does not work over SSH connections, and there may be other cases where it also doesn't work. So don't come for me if it's giving confused. 😭
And a legit reason to disable this feature? If you find it's interfering with legitimate accessibility software (or software that uses the accessibility APIs), because secure input prevents any application from reading keyboard events. That part is important — it's a security thing, not a vibe thing. 🔐
macos-secure-input-indication— Iftrue, Ghostty shows a graphical indication when secure input is enabled. This indication is generally recommended so you know when secure input is on. 👀
Normally, secure input is only active when a password prompt is displayed or when it's manually (and typically temporarily) enabled. But if you always have secure input enabled, that little indication can be distracting and you may want to disable it. Totally your call.
macos-applescript— Iftrue, Ghostty exposes and handles the built-in AppleScript dictionary on macOS. 🍎
If false, all AppleScript interactions are disabled. That includes AppleScript commands and AppleScript object lookup for windows, tabs, and terminals.
The default is true.
macos-icon— Customize the macOS app icon. It's giving customization era. 🎀
This only affects the icon that appears in the dock, application switcher, etc. It does not affect the icon in Finder, because that's controlled by a hardcoded value in the signed application bundle and can't be changed at runtime. For more details on what exactly is affected, see the NSApplication.icon Apple documentation — that's the API being used to set the icon.
Valid values:
official— Use the official Ghostty icon. Classic. Iconic, even. 👑blueprint,chalkboard,microchip,glass,holographic,paper,retro,xray— Official variants of the Ghostty icon hand-created by artists (no AI). Respect the artists, fr fr. 🎨custom— Use a completely custom icon. The location must be specified using the additionalmacos-custom-iconconfiguration.custom-style— Use the official Ghostty icon but with custom styles applied to various layers. The custom styles must be specified using the additionalmacos-icon-prefixed configurations. Themacos-icon-ghost-colorandmacos-icon-screen-colorconfigurations are required for this style.
WARNING: The custom-style option is experimental. We may change the format of the custom styles in the future. We're still finalizing the exact layers and customization options that will be available. So don't build your whole personality around it just yet. 💀
Other caveats:
- The icon in the update dialog will always be the official icon. This is because the update dialog is managed through a separate framework and cannot be customized without significant effort.
macos-custom-icon— The absolute path to the custom icon file. Supported formats includePNG,JPEG, andICNS.
Defaults to ~/.config/ghostty/Ghostty.icns.
macos-icon-frame— The material to use for the frame of the macOS app icon. Very aesthetic. ✨
Valid values:
aluminum— A brushed aluminum frame. This is the default.beige— A classic 90's computer beige frame. Vintage slay. 🖥️plastic— A glossy, dark plastic frame.chrome— A shiny chrome frame.
Note: This configuration is required when macos-icon is set to custom-style.
macos-icon-ghost-color— The color of the ghost in the macOS app icon. 👻
Note: This configuration is required when macos-icon is set to custom-style.
Specified as either hex (#RRGGBB or RRGGBB) or a named X11 color.
macos-icon-screen-color— The color of the screen in the macOS app icon. 🌈
The screen is a linear gradient, so you can specify multiple colors that make up the gradient. Up to 64 comma-separated colors may be specified as either hex (#RRGGBB or RRGGBB) or as named X11 colors. The first color is the bottom of the gradient and the last color is the top of the gradient.
Note: This configuration is required when macos-icon is set to custom-style.
macos-shortcuts— Whether macOS Shortcuts are allowed to control Ghostty. Shortcut girlies, this one's for you. 🩷
Ghostty exposes a number of actions that allow Shortcuts to control and interact with Ghostty. This includes creating new terminals, sending text to terminals, running commands, invoking any keybind action, etc.
This is a powerful feature but can be a security risk if a malicious shortcut is able to be installed and executed. Therefore, this configuration allows you to disable this feature. Stay safe out there. 🛡️
Valid values are:
ask— Ask the user for permission. Ghostty will remember this choice and never ask again. This is similar to other macOS permissions such as microphone access, camera access, etc.allow— Allow Shortcuts to control Ghostty without asking.deny— Deny Shortcuts from controlling Ghostty.
Available since: 1.2.0
linux-cgroup— Put every surface (tab, split, window) into a transient systemd scope. This is lowkey the resource-management main character. 🐧
This allows per-surface resource management. For example, if a shell program is using too much memory, only that shell will be killed by the oom monitor instead of the entire Ghostty process. Similarly, if a shell program is using too much CPU, only that surface will be CPU-throttled. Not the whole app catching strays. 💅
This will cause startup times to be slower (a hundred milliseconds or so), so the default value is "single-instance." In single-instance mode, only one instance of Ghostty is running (see gtk-single-instance) so the startup time is a one-time cost. Additionally, single instance Ghostty is much more likely to have many windows, tabs, etc. so cgroup isolation is a big benefit.
This feature requires systemd. If systemd is unavailable, cgroup initialization will fail. By default, this will not prevent Ghostty from working (see linux-cgroup-hard-fail).
Changing this value and reloading the config will not affect existing surfaces.
Valid values are:
never— Never use cgroups.always— Always use cgroups.single-instance— Enable cgroups only for Ghostty instances launched as single-instance applications (seegtk-single-instance).
linux-cgroup-memory-limit— Memory limit for any individual terminal process (tab, split, window, etc.) in bytes. If this is unset then no memory limit will be set. 🧠
Note that this sets the MemoryHigh setting on the transient systemd scope, which is a soft limit. You should configure something like systemd-oom to handle killing processes that have too much memory pressure.
Changing this value and reloading the config will not affect existing surfaces.
See the systemd.resource-control manual page for more information: https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html
linux-cgroup-processes-limit— Number of processes limit for any individual terminal process (tab, split, window, etc.). If this is unset then no limit will be set. 🧮
Note that this sets the TasksMax setting on the transient systemd scope, which is a hard limit.
Changing this value and reloading the config will not affect existing surfaces.
See the systemd.resource-control manual page for more information: https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html
linux-cgroup-hard-fail— If this isfalse, then creating a transient systemd scope (forlinux-cgroup) will be allowed to fail and the failure is ignored. This is useful if you view cgroup isolation as a "nice to have" and not a critical resource management feature, because surface creation will not fail if systemd APIs fail. Very chill of you. 🦋
If this is true, then any transient systemd scope creation failure will cause surface creation to fail. No vibes-based forgiveness. It's giving strict.
Changing this value and reloading the config will not affect existing surfaces.
gtk-opengl-debug— Enable or disable GTK's OpenGL debugging logs. The default istruefor debug builds,falsefor all others.
Available since: 1.1.0
gtk-single-instance— Iftrue, the Ghostty GTK application will run in single-instance mode: each newghosttyprocess launched will result in a new window if there is already a running process.
If false, each new ghostty process will launch a separate application.
If detect, Ghostty will assume true (single instance) unless one of the following scenarios is found:
TERM_PROGRAMenvironment variable is a non-empty value. In this case, we assume Ghostty is being launched from a graphical terminal session and you want a dedicated instance.- Any CLI arguments exist. In this case, we assume you are passing custom Ghostty configuration. Single instance mode inherits the configuration from when it was launched, so we must disable single instance to load the new configuration.
If either of these scenarios is producing a false positive, you can set this configuration explicitly to the behavior you want. You're the main character of your own config, bestie. 👑
The pre-1.2 option desktop has been deprecated. Please replace this with detect.
The default value is detect.
Note that debug builds of Ghostty have a separate single-instance ID so you can test single instance without conflicting with release builds. Convenient, honestly.
gtk-titlebar— When enabled, the full GTK titlebar is displayed instead of your window manager's simple titlebar. The behavior of this option will vary with your window manager. Window manager girlies know. 🪟
This option does nothing when window-decoration is none or when running under macOS.
gtk-tabs-location— Determines the side of the screen that the GTK tab bar will stick to.Top,bottom, andhiddenare supported. The default istop. 📌
When hidden is set, a tab button showing how many tabs you have pops up in the title bar. That button can open a tab overview so you can see all your tabs. No title bar on your window? Totally fine — use the toggle_tab_overview action in a keybind instead, or just switch tabs with keybinds like a normal person. 💅
gtk-tabs-inverted— if true, each tab's close button shows up at the start of the tab (the left, in left-to-right languages) and the tab's icon sits at the end. This applies to the tab bar and the tab overview. GTK only, bestie.
Available since: 1.4.0
gtk-titlebar-hide-when-maximized— when this is true, the titlebar dips out when the window is maximized and comes back when it's unmaximized. GTK only. ✨
Available since: 1.1.0
gtk-toolbar-style— decides how the top and bottom bars' tab bar looks. Valid values are:flat— top and bottom bars are flat, merged with the terminal window.raised— top and bottom bars cast a shadow onto the terminal area.raised-border— basicallyraised, but the shadow gets swapped for a subtler border.
gtk-titlebar-style— the style of the GTK titlebar. Available values arenativeandtabs.
The native titlebar style is your classic titlebar: a title, a couple buttons, window controls, the whole vibe. If you've got multiple tabs open in the window, a separate tab bar shows up below the titlebar.
The tabs titlebar style merges the tab bar and the traditional titlebar into one. This frees up vertical space if you're a multiple-tabs girlie. One limitation though, and it's real: you can't drag the window around by the titles anymore (they're tab titles now, periodt). Other areas of the tabs title bar can still be used to drag the window.
The default style is native.
gtk-wide-tabs— if true (and it's the default), Ghostty's GTK tabs go "wide." Wide tabs are the new typical Gnome style where tabs fill up whatever space they have. Set this to false and tabs only take up the space they actually need — that's the old style. 🌸gtk-horizontal-tab-scroll— if true (default again, icon), two-finger horizontal scrolling on a touchpad switches between tabs. Scroll left → next tab, scroll right → previous tab. Set it to false to turn that off completely.
Available since 1.4.0.
gtk-custom-css— custom CSS files to load. 🎀
GTK CSS documentation lives at these links:
- https://docs.gtk.org/gtk4/css-overview.html — an overview of GTK CSS.
- https://docs.gtk.org/gtk4/css-properties.html — a full list of supported CSS properties.
Wanna tweak Ghostty's CSS in real time? Launch Ghostty with env GTK_DEBUG=interactive ghostty and use the GTK Inspector. Errors in your CSS files get reported in the terminal you started Ghostty from, too. More info about the GTK Inspector is at https://developer.gnome.org/documentation/tools/inspector.html.
This configuration can be repeated multiple times to load multiple files. Prepend a ? character to the file path to suppress errors when the file doesn't exist. And if you actually want to include a file whose name begins with a literal ? character, wrap the file path in double quotes ("). The file size limit for a single stylesheet is 5MiB.
Available since: 1.1.0
desktop-notifications— if true (default), apps running in the terminal can pop desktop notifications using certain escape sequences like OSC 9 or OSC 777. 🦋progress-style— if true (default), apps running in the terminal can show graphical progress bars using the ConEmu OSC 9;4 escape sequence. If false, those progress bar sequences get silently ignored. No drama, just nothing.bold-color— changes the color used for bold text in the terminal.
You can set it to a specific color using the same format as background or foreground (e.g. #RRGGBB, but other formats work too — see that aforementioned documentation). If you set a specific color, that color is always used for the default bold text color. It'll set the rest of the bold colors to bright.
You can also set it to bright, which uses the bright color palette for bold text. So if the text is red, the bold version uses bright red. The terminal palette is set with palette, but the terminal application itself can override it with escape sequences such as OSC 4. (Since Ghostty 1.2.0, the old config bold-is-bright is deprecated and replaced by this usage — RIP to a real one.)
Available since Ghostty 1.2.0.
faint-opacity— the opacity level (the opposite of transparency) of faint text. A value of1is fully opaque and0is fully transparent. Anything below0or above1gets clamped to the nearest valid value. Math said no. 😭
Available since Ghostty 1.2.0.
term— this sets theTERMenvironment variable. HACK alert 🚨: we set it with anxtermprefix because vim uses that to enable key protocols (specifically, this enablesmodifyOtherKeys), among other features. There's an option in vim to change this::set keyprotocol=ghostty:kitty, but a bug in the implementation stops it from working properly. https://github.com/vim/vim/pull/13211 fixes it.enquiry-response— the string to send when we receive ENQ (0x05) from the command we're running. Defaults to an empty string if not set.async-backend— configures the low-level API to use for async IO, eventing, etc.
Most people should leave this on auto. It automatically detects situations where APIs might not be available (say, io_uring on certain hardened kernels) and falls back to a different API. But if you wanna force a specific backend for whatever reason, go off — set it here. 💅
Based on various benchmarks, we haven't found a statistically significant difference between backends when it comes to memory, CPU, or latency. The choice of backend is more about compatibility and features.
Available options:
auto— automatically choose the best backend for the platform based on what's available.epoll— use the epoll API.io_uring— use the io_uring API.
If the backend you picked isn't available on the platform, Ghostty falls back to an automatically chosen backend that is available.
Changing this value requires a full application restart to take effect. Like, actually restart it.
This is only supported on Linux, since that's the only platform where we have multiple options. On macOS we always use kqueue, no notes.
Available since: 1.2.0
auto-update— controls Ghostty's auto-update functionality. Currently only supported on macOS, since Linux builds are distributed via package managers that Ghostty doesn't centrally control. 🍓
Checking or downloading an update doesn't send any info to the project beyond standard network info mandated by the underlying protocols. Put another way: Ghostty doesn't explicitly add any tracking to the update process. The update process works by downloading info about the latest version and comparing it client-side against your current version.
Valid values are:
off— disable auto-updates.check— check for updates and notify the user if one's available, but don't automatically download or install it.download— check for updates, automatically download the update, notify the user, but don't automatically install it.
If unset, we defer to Sparkle's default behavior, which respects the preference stored in the standard user defaults (defaults(1)).
Changing this value at runtime works after a small delay.
auto-update-channel— the release channel to use for auto-updates.
The default value matches the release channel of the currently running Ghostty version. Download a pre-release version of Ghostty and this gets set to tip, so you receive pre-release updates. Download a stable version and this gets set to stable, so you receive stable updates.
Valid values are:
stable— stable, tagged releases such as"1.0.0".tip— pre-release versions generated from each commit to the main branch. This is the version that was in use during private beta testing by thousands of people. It's generally stable, but it'll likely have more bugs than the stable channel. 🙈
Changing this configuration requires a full restart of Ghostty to take effect.
This only works on macOS, since only macOS has an auto-update feature.
🎀 KEYBIND ACTIONS 🎀
ignore— ignore this key combination. 🙅
Ghostty won't process this combo, and won't forward it to the child process inside the terminal either — but the OS or other applications might still process it. So like, not guaranteed ignored, iykyk.
unbind— unbind a previously bound key binding.
This can't unbind bindings that weren't bound by Ghostty or by the user (e.g. bindings set by the OS or some other application). Sorry babe, not your jurisdiction.
csi— send a CSI sequence.
The value should be the CSI sequence without the CSI header (ESC [ or \x1b[).
For example, csi:0m can be sent to reset all styles of the current text. ✨
esc— send an ESC sequence.text— send the specified text.
Uses Zig string literal syntax. This is currently not validated. If the text is invalid (i.e. it contains an invalid escape sequence), the error will currently only show up in logs. So check your logs, bestie.
cursor_key— send data to the pty depending on whether cursor key mode is enabled (application) or disabled (normal).reset— reset the terminal. 🔥
This can fix a lot of issues when some running program has yeeted your terminal into a fully broken state — it's literally equivalent to running the reset command. 💫
⚠️ but bestie, be careful: if you do this while you're inside a TUI program like vim, it may break the program. And if you do it from a shell, you might have to press enter afterwards to get a fresh prompt. You've been warned 🫶
copy_to_clipboard— copies your selected text to the clipboard. 🎀
Valid values:
plain
Copy the selection as plain text only. Simple, clean, no drama.
vt
Copy the selection as plain text but preserving terminal escape sequences (so colors and styles come along for the ride).
html
Copy the selection as HTML, keeping colors and styles as actual HTML markup.
mixed(default)
Puts multiple representations on the clipboard at once (like plain text and HTML), each one tagged with its content type so the receiving OS or app can pick whichever representation is most appropriate when you paste. Iconic multitasking behavior, honestly.
paste_from_clipboard— paste whatever's in the default clipboard. 📋paste_from_selection— paste whatever's in the selection clipboard.copy_url_to_clipboard— if there's a URL chilling under your cursor, this copies it to the default clipboard. 🔗copy_title_to_clipboard— copies the terminal title to the clipboard. If the terminal title isn't set or is empty, this does literally nothing (no effect, no vibes).increase_font_size— makes the font size bigger by the amount you specify, in points (pt).
So like, increase_font_size:1.5 increases the font size by 1.5 points. ✨
decrease_font_size— makes the font size smaller by the amount you specify, in points (pt).
For example, decrease_font_size:1.5 decreases the font size by 1.5 points.
reset_font_size— resets the font size back to the original size you configured. Back to factory settings, bestie. 🧚set_font_size— sets the font size to exactly the size you specify, in points (pt).
For example, set_font_size:14.5 sets the font size to 14.5 points.
search— starts a search for the text you give it. If the text is empty, the search gets canceled. Heads up though: a canceled search will not disable any GUI elements that are showing the search — for that you gotta use the explicitend_searchbinding. 🦋
And if a previous search is already active? It gets replaced.
search_selection— starts a search for whatever text you currently have selected. If there's no selection, this does nothing at all. If a search is already active, this changes the search terms instead.navigate_search— navigates through the search results. If there's no active search, this just doesn't get performed.
Valid values: previous, next.
start_search— starts a search if it isn't already started. It doesn't set any search terms, it just opens the UI for searching. Lowkey just the vibe-setter.end_search— ends the current search if there is one, and hides any GUI elements. 🫧clear_screen— clears the screen and all the scrollback. Everything. Gone. Fresh start energy.select_all— selects all text on the screen. 👑scroll_to_top— scrolls to the top of the screen.scroll_to_bottom— scrolls to the bottom of the screen.scroll_to_selection— scrolls to wherever your selected text is.scroll_to_row— scrolls to the absolute row you give it, where0is the first row.scroll_page_up— scrolls the screen up by one whole page.scroll_page_down— scrolls the screen down by one whole page.scroll_page_fractional— scrolls the screen by the fraction of a page you specify.
Positive values scroll downwards, negative values scroll upwards. 🔥
For example, scroll_page_fractional:0.5 scrolls the screen downwards by half a page, while scroll_page_fractional:-1.5 scrolls it upwards by one and a half pages.
scroll_page_lines— scrolls the screen by the number of lines you specify.
Positive values scroll downwards, negative values scroll upwards.
For example, scroll_page_lines:3 scrolls the screen downwards by 3 lines, while scroll_page_lines:-10 scrolls it upwards by 10 lines. ⭐
adjust_selection— adjusts the current selection in the direction or position you give it, relative to the cursor.
🚨 WARNING: this does not create a new selection, and it does absolutely nothing when there isn't one already. No selection, no service, no cap.
Valid arguments are:
left,right
Adjust the selection one cell to the left or right, respectively.
up,down
Adjust the selection one line upwards or downwards, respectively.
page_up,page_down
Adjust the selection one page upwards or downwards, respectively.
home,end
Adjust the selection to the top-left or the bottom-right corner of the screen, respectively.
beginning_of_line,end_of_line
Adjust the selection to the beginning or the end of the line, respectively.
jump_to_prompt— jumps the viewport forward or back by the number of prompts you give it. 🦋
Requires shell integration. (iykyk)
Positive values scroll downwards, negative values scroll upwards.
write_scrollback_file— writes the entire scrollback into a temporary file using the action you specify. The action decides what happens with the filepath.
Valid actions are:
copy
Copies the file path into the clipboard.
paste
Pastes the file path into the terminal.
open
Opens the file in the default OS editor for text files. 🌸
The default OS editor is determined by using open on macOS and xdg-open on Linux.
write_screen_file— writes the contents of the screen into a temporary file using the action you specify.
See write_scrollback_file for the possible actions. 👀
write_selection_file— writes the currently selected text into a temporary file using the action you specify.
See write_scrollback_file for the possible actions.
Does nothing when no text is selected. (yep, same rule as before 🫠)
new_window— opens a new window. 🪟
And if the app isn't currently focused, this brings it to the front. Main character behavior.
new_tab— opens a new tab.previous_tab— goes to the previous tab.next_tab— goes to the next tab.last_tab— goes to the last tab.goto_tab— goes to the tab with the specific index you give it, starting from1.
If the tab number is higher than the number of tabs, it just goes to the last tab. No error, no crash, just vibes.
move_tab— moves a tab by a relative offset. 🎀
Positive values move the tab forwards, negative values move it backwards. And if the new position is out of bounds, it wraps around cyclically within the tab list. That's some genuinely elegant behavior.
For example, move_tab:1 moves the tab one position forwards, and if it was already the last tab in the list, it wraps around and becomes the first tab in the list. Likewise, move_tab:-1 moves the tab one position backwards, and if it was the first tab, then it becomes the last tab. 💅
move_tab_to_new_window— moves a tab to a new window. Slay, relocate.toggle_tab_overview— toggles the tab overview.
This is only supported on Linux, and only when the system's libadwaita version is 1.4 or newer. You can find the current libadwaita version by running ghostty +version. 🔍
prompt_surface_title— changes the title of the current focused surface via a pop-up prompt.prompt_tab_title— changes the title of the current tab via a pop-up prompt. The title you set through this prompt overrides any title set by the terminal, and it persists across focus changes within the tab. 👑prompt_window_title— changes the title of the current window via a pop-up prompt. The title set via this prompt overrides any title set by the terminal and persists across focus changes within the tab.
Only implemented on Linux.
set_surface_title— sets the title for the current focused surface.
If the title is empty, the surface title gets reset to an empty title.
set_tab_title— sets the title for the current focused tab.
If the title is empty, the tab title override is cleared. 🫧
set_window_title— sets the title for the current focused window.
If the title is empty, the tab title override is cleared.
Only implemented on Linux.
new_split— creates a new split in the direction you specify. 🪟✨
Valid arguments:
right,down,left,up
Creates a new split in the corresponding direction.
auto
Creates a new split along the larger direction. So like, if the parent split is currently wider than it is tall, then a left-right split gets created, and vice versa. It thinks for you, honestly.
goto_split— focuses on a split either in the direction you specify (right,down,leftandup), or in the adjacent split in the order of creation (previousandnext).goto_window— focuses on either the previous window or the next one (previous,next).toggle_split_zoom— zooms in or out of the current split.
When a split is zoomed into, it takes up the entire space in the current tab, hiding the other splits. The tab or tab bar also reflects this by displaying an icon indicating the zoomed state. Full main character energy for that one split. 💅
toggle_readonly— toggles read-only mode for the current surface.
When a surface is in read-only mode:
- No input is sent to the PTY (mouse events, key encoding) 🚫
- Input can still be used at the terminal level to make selections, copy/paste (keybinds), scroll, etc.
- Warn before quit is always enabled in this state, even if an active process is not running.
resize_split— resizes the current split in the direction and amount you specify, in pixels. The two arguments should be joined with a comma (,), like inresize_split:up,10. 📐equalize_splits— equalizes the size of all splits in the current window. Everyone gets the same share, no favorites.reset_window_size— resets the window to the default size. The "default size" is the size that a new window would be created with. This has no effect if the window is fullscreen. 🖥️
Only implemented on macOS. 🍎
inspector 🕵️♀️
Control the visibility of the terminal inspector. Valid arguments: toggle, show, hide. Pick your fighter, bestie ✨
show_gtk_inspector 🧐
Show the GTK inspector. Has no effect on macOS.
show_on_screen_keyboard ⌨️🌸
Show the on-screen keyboard if one is present.
Only implemented on Linux (GTK). On GNOME, the “Screen Keyboard” accessibility feature must be turned on, which can be found under Settings > Accessibility > Typing. Other platforms are as of now untested. 🫶
open_config 📝✨
Open the configuration file in an editor.
os_open— Use the OS’s default editor to edit the configuration file. This is the default action. (Available since 1.4.0)new_window— Launch the editor specified in$EDITORor$VISUALin a new Ghostty window to edit the configuration file. GTK only. (Available since 1.4.0.)
reload_config 🔄💖
Reload the configuration.
The exact meaning depends on the app runtime in use, but this usually involves re-reading the configuration file and applying any changes. Note that not all changes can be applied at runtime. Lowkey important, bestie 😌
close_surface 🚪💅
Close the current “surface”, whether that is a window, tab, split, etc.
This might trigger a close confirmation popup, depending on the value of the confirm-close-surface configuration setting.
close_tab 🗂️✨
Close the specified tabs and all splits therein.
Valid values:
this(default) — Close the current tab and all splits within it.other— Close every tab in the current window except the current tab.right— Close every tab to the right of the current tab.
This might trigger a close confirmation popup, depending on the value of the confirm-close-surface configuration setting.
close_window 🪟👋
Close the current window and all tabs and splits therein.
This might trigger a close confirmation popup, depending on the value of the confirm-close-surface configuration setting.
close_all_windows 💀
Close all windows.
WARNING: This action has been deprecated and has no effect on either Linux or macOS. Users are instead encouraged to use all:close_window instead. No cap, it’s giving retired icon 🫠
toggle_maximize 🖥️🌱
Maximize or unmaximize the current window.
On macOS, this zooms the window, which is the closest equivalent since macOS has no concept of a maximized window.
toggle_fullscreen 🖼️✨
Fullscreen or unfullscreen the current window.
toggle_window_decorations 🎀🪟
Toggle window decorations (titlebar, buttons, etc.) for the current window.
Only implemented on Linux.
toggle_window_float_on_top 🦋📌
Toggle whether the terminal window should always float on top of other windows even when unfocused.
Terminal windows always start as normal (not float-on-top) windows.
Only implemented on macOS.
toggle_secure_input 🔒💖
Toggle secure input mode.
This is used to prevent apps from monitoring your keyboard input when entering passwords or other sensitive information.
This applies to the entire application, not just the focused terminal. You must manually untoggle it or quit Ghostty entirely to disable it.
Only implemented on macOS, as this uses a built-in system API.
toggle_mouse_reporting 🖱️🌸
Toggle mouse reporting on or off.
When mouse reporting is disabled, mouse events will not be reported to terminal applications even if they request it. This allows you to always use the mouse for selection and other terminal UI interactions without applications capturing mouse input.
This can also be controlled via the mouse-reporting configuration option.
toggle_command_palette 🪄🔍
Toggle the command palette.
The command palette is a popup that lets you see what actions you can perform, their associated keybindings (if any), a search bar to filter the actions, and the ability to then execute the action.
This requires libadwaita 1.5 or newer on Linux. The current libadwaita version can be found by running ghostty +version.
toggle_quick_terminal 🪟⚡️
Toggle the quick terminal.
The quick terminal, also known as the “Quake-style” or drop-down terminal, is a terminal window that appears on demand from a keybinding, often sliding in from a screen edge such as the top. This is useful for quick access to a terminal without having to open a new window or tab.
The terminal state is preserved between appearances, so showing the quick terminal after it was already hidden would display the same window instead of creating a new one.
As quick terminals are often useful when other windows are currently focused, they are best used with global keybinds. For example, one can define the following key bind to toggle the quick terminal from anywhere within the system by pressing Cmd+`:
keybind = global:cmd+backquote=toggle_quick_terminalThe quick terminal has some limitations:
- Only one quick terminal instance can exist at a time.
- Unlike normal terminal windows, the quick terminal will not be restored when the application is restarted on systems that support window restoration like macOS.
- On Linux, the quick terminal is only supported on Wayland and not X11, and only on Wayland compositors that support the
wlr-layer-shell-v1protocol. In practice, this means that only GNOME users would not be able to use this feature. - On Linux, slide-in animations are only supported on KDE, and when the “Sliding Popups” KWin plugin is enabled. If you do not have this plugin enabled, open System Settings > Apps & Windows > Window Management > Desktop Effects, and enable the plugin in the plugin list. Ghostty would then need to be restarted fully for this to take effect.
- Quick terminal tabs are only supported on Linux and not on macOS. This is because tabs on macOS require a title bar.
- On macOS, a fullscreened quick terminal will always be in non-native fullscreen mode. This is a requirement due to how the quick terminal is rendered.
See the various configurations for the quick terminal in the configuration file to customize its behavior. 💜
toggle_visibility 👀🫶
Show or hide all windows. If all windows become shown, we also ensure Ghostty becomes focused. When hiding all windows, focus is yielded to the next application as determined by the OS.
Note: When the focused surface is fullscreen, this method does nothing.
Only implemented on macOS.
toggle_background_opacity 🌫️✨
Toggle the window background opacity between transparent and opaque.
This does nothing when background-opacity is set to 1 or above.
When background-opacity is less than 1, this action will either make the window transparent or not depending on its current transparency state.
Only implemented on macOS.
check_for_updates 🔄👑
Check for updates.
Only implemented on macOS.
undo ↩️💫
Undo the last undoable action for the focused surface or terminal, if possible. This can undo actions such as closing tabs or windows.
Not every action in Ghostty can be undone or redone. The list of actions that support undo/redo is currently limited to:
- New window, close window
- New tab, close tab
- New split, close split
All actions are only undoable/redoable for a limited time. For example, restoring a closed split can only be done for some number of seconds since the split was closed. The exact amount is configured with the undo-timeout configuration settings.
The undo/redo actions being limited ensures that there is bounded memory usage over time, closed surfaces don’t continue running in the background indefinitely, and the keybinds become available for terminal applications to use.
Only implemented on macOS.
redo ↪️🌸
Redo the last undoable action for the focused surface or terminal, if possible. See “undo” for more details on what can and cannot be undone or redone.
end_key_sequence 🔚⌨️
End the currently active key sequence, if any, and flush the keys up to this point to the terminal, excluding the key that triggered this action.
For example: ctrl+w>escape=end_key_sequence would encode ctrl+w to the terminal and exit the key sequence.
Normally, an invalid sequence will reset the key sequence and flush all data including the invalid key. This action allows you to flush only the prior keys, which is useful when you want to bind something like a control key (ctrl+w) but not send additional inputs.
activate_key_table 🗝️✨
Activate a named key table (see keybind configuration documentation). The named key table will remain active until deactivate_key_table is called. If you want a one-shot key table activation, use the activate_key_table_once action instead.
If the named key table does not exist, this action has no effect and performable will report false.
If the named key table is already the currently active key table, this action has no effect and performable will report false.
activate_key_table_once 🗝️🫧
Same as activate_key_table, but the key table will only be active until the first valid keybinding from that table is used (including any defined catch_all bindings).
The “once” check is only done if this is the currently active key table. If another key table is activated later, then this table will remain active until it pops back out to being the active key table.
deactivate_key_table 🔒🌙
Deactivate the currently active key table, if any. The next most recently activated key table (if any) will become active again. If no key table is active, this action has no effect.
deactivate_all_key_tables— turns off every single active key table at once, like closing all your open tabs (the emotional kind). If there's no active key table to begin with, this reportsperformableasfalse. no vibes to kill, basically 💀quit— quits Ghostty. that's it, that's the whole thing. bye bestie 👋crash— crashes Ghostty in whichever thread you picked for the focused surface. yes, on purpose. we're doing this.
⚠️ WARNING: this is a hard crash (a panic, fr fr) and data can be lost. like, actually. do not do this while you have unsaved stuff, bestie, i'm begging 😭
so why does this exist? the whole point of this action is to test crash handling. for some users it's genuinely useful to poke at the crash reporting functionality and figure out whether all of it works the way it's supposed to. vibe check for your crash reporter 🧚
the value you give it picks where the crash happens:
main— crash on the main (GUI) thread. main character energy, but make it fatal 🔥io— crash on the IO thread for the focused surface.render— crash on the render thread for the focused surface.
🌸 FILES 🌸
$XDG_CONFIG_HOME/ghostty/config.ghostty— where your default config file lives. this is the one ✨$HOME/Library/Application Support/com.mitchellh.ghostty/config.ghostty— on macOS, this is where the default config file lives. and plot twist: this location takes precedence over the XDG environment locations. so if you've got both, macOS wins, sorry 🍎$LOCALAPPDATA/ghostty/config.ghostty— on Windows, if$XDG_CONFIG_HOMEisn't set,$LOCALAPPDATAis where Ghostty goes looking for configuration files.
🌈 ENVIRONMENT 🌈
XDG_CONFIG_HOME— the default spot for your configuration files. classic.$HOME/Library/Application Support/com.mitchellh.ghostty— MACOS ONLY, and it's the default location for configuration files. remember how we said it takes precedence over the XDG environment locations? yeah. that. 🫶LOCALAPPDATA— WINDOWS ONLY: the alternate location to search for configuration files.
💀 BUGS 💀
found something cursed? take it to the GitHub issues, that's where the chaos gets triaged:
https://github.com/ghostty-org/ghostty/issues👑 AUTHOR 👑
Mitchell Hashimoto m@mitchellh.com and the Ghostty contributors — an iconic duo, honestly.
the contributor graph lives here if you wanna see the whole squad:
https://github.com/ghostty-org/ghostty/graphs/contributors🦋 SEE ALSO 🦋
ghostty(1)— the other half of the story, go read it 💖
and that's a wrap on the whole page, bestie 🎀 you made it to the very end — we're so proud. this was Version 1.4.0-arch1, page GHOSTTY(5), and no, there's no date printed on this one, so consider this your lil timestamp-free sign-off. go write a config, break nothing, and slay 💅✨
📦 where this page comes from
- arch rolling: ghostty 1.4.0-1 · MIT
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms