Settings and appearance

Configuration file

Afterglow reads $XDG_CONFIG_HOME/afterglow/config.json. The usual path is ~/.config/afterglow/config.json. Afterglow reloads this file when it changes. A file that cannot be read, does not parse or does not hold a JSON object keeps the current settings. At the start there are no current settings to keep. Afterglow then uses the defaults, but with Scripts.enabled and Control.enabled off, because the file can turn them off. They come on when the file holds a JSON object that does not turn them off. A -o option that gives one of them a boolean value still applies. A file that becomes empty in the meantime keeps them off, because an editor that saves in place empties the file first. A configuration file that is a symbolic link to a file that does not exist counts as a file that cannot be read. A file that holds Terminal.fileTransferPassword and that other users can read gives a warning. Make it readable by you only (chmod 600). A deleted file gives every setting its default. An empty file gives the defaults too, when it held no settings before, for example after touch. A file that held settings and becomes empty keeps them, because an editor that saves in place empties the file first. Delete the file to go back to the defaults. Afterglow shows a notice and logs a warning for unknown keys and for values that it replaces with a default.

The file holds only the values that differ from the defaults. Afterglow does not create it on the first start. Afterglow creates it when it saves a setting for the first time, for example the shaders that a script package suggests. The open_config action creates a file that holds an empty JSON object if there is no file. Only your user can read the file that Afterglow creates.

The configuration reference lists all keys, defaults and ranges. Group names and key names are case-sensitive.

{
"Font": {"size": 12, "antialiasing": "grayscale"},
"Colors": {"theme": "afterglow-dark"},
"Terminal": {"shellIntegration": "enabled", "scrollback": 10000},
"Window": {"padding": 8}
}

Launch options

OptionFunction
-o Group.key=valueChanges one setting for this launch
--configReads another configuration file. Its directory then holds the themes, shaders, shader-presets and scripts directories
--classSets the Wayland application ID for window rules
--titleSets a fixed window title
--holdKeeps the window open after an -e program stops
-e, --executeRuns the rest of the command line instead of the shell
-d, --working-directoryStarts in the given directory
--quick-terminalShows or hides the quick terminal
afterglow -o Font.size=14 -o Colors.theme=afterglow-light

The first three options apply to the complete process. A launch with these options starts a separate process. Other launches can use an existing process that runs the same executable file. A development build or replacement executable starts a separate process.

Desktop controls

Tabs, menus, prompts and search use the desktop Qt style, palette and font. On Plasma, this requires qqc2-desktop-style and platform theme integration. QT_QUICK_CONTROLS_STYLE can select another installed style. The variable applies only when the launch starts a new process. Terminal fonts and colors have separate settings.

Fonts

SettingDefaultFunction
Font.familyemptyFont family of regular text. Empty uses the desktop’s fixed-width font.
Font.size0Size in points, from 4 to 96. 0 uses the size of the desktop’s fixed-width font.
Font.featurescalt, ligaOpenType features in HarfBuzz syntax
Font.fallbackFamiliesemptyFamilies that supply missing characters before the system fallback
Font.symbolMapemptyFamilies for codepoint ranges, such as Nerd Font symbols

If the family is not installed, fontconfig selects the nearest match. Without a desktop font setting, Afterglow uses the monospace alias at 11 points. Afterglow draws the characters in the table below itself, so that they fill the cell and join the next cell. Font.symbolMap does not change these characters. The font draws the other characters of these blocks, such as the pictures and the digits.

CharactersCode points
Box drawing and block elementsU+2500 to U+259F
Braille patternsU+2800 to U+28FF
Powerline separatorsU+E0B0 to U+E0BF
Sextants, smooth mosaics and trianglesU+1FB00 to U+1FB6F, U+1FB9A to U+1FB9F
Eighth blocks, quarter blocks, third blocks and half shadesU+1FB70 to U+1FB92, U+1FB94, U+1FBCE, U+1FBCF, U+1FBE4 to U+1FBE7
Diagonal box drawingU+1FBA0 to U+1FBAE, U+1FBD0 to U+1FBDF
Separated quadrants and sextantsU+1CC21 to U+1CC2F, U+1CE51 to U+1CE8F
OctantsU+1CD00 to U+1CDE5
Sixteenth blocks and partial quarter blocksU+1CE90 to U+1CEAF

Font rendering

SettingValuesDefault
Font.antialiasinggrayscale, none, rgb, bgrgrayscale
Font.hintingnone, light, fulllight
Font.gamma0.5–3.01.0

Font.antialiasing=none gives monochrome glyph edges. Light hinting aligns glyphs vertically. Full hinting aligns both axes. RGB and BGR refer to the horizontal order of display subpixels. Select the order that agrees with your display.

afterglow -o Font.antialiasing=rgb -o Font.gamma=1.2

Subpixel modes use separate filtered coverage for each color channel. Active shaders or window transparency cause an automatic change to grayscale text. Pane effects are shaders. They run while a pane is remote (afterglow ssh) or in another context. Such a pane makes all text in its window grayscale. Overlay fades are also shaders. While an overlay fades in or out, all text in its window is grayscale. A transparent pane background also uses grayscale text. An opaque window without shaders can use subpixel text again. Grayscale can give better results when the compositor scales or rotates the output.

Gamma changes glyph coverage with coverage^(1/gamma). It does not change display gamma or scene color space. Higher values make antialiased edges stronger. A value of 1.0 keeps the standard coverage. Monochrome edges remain binary. Color emoji keep their original pixels. Procedural box and powerline shapes use their own antialiasing with coverage gamma. Qt Quick renders the controls separately from terminal cells.

Themes

Colors.theme selects a theme. A theme replaces each color that it sets. Colors that it leaves out keep their Colors values, except the divider and popup border colors. A theme without a divider color gets one a fifth of the way from its background color to its text color. A theme without a popup border color gets the color halfway from its background color to its text color. With a theme, Colors.divider and Colors.popupBorder are not used. Without a theme, Afterglow derives an empty Colors.divider and Colors.popupBorder in the same way, from Colors.background and Colors.foreground.

Afterglow first searches the themes directory beside the configuration file, normally $XDG_CONFIG_HOME/afterglow/themes. With --config DIR/config.json, it searches DIR/themes instead. It then searches afterglow/themes in each XDG data directory, starting with ~/.local/share. It then searches the supplied themes in the table below. Last, it searches the themes that other terminals installed:

TerminalDirectoriesFile
Ghostty~/.config/ghostty/themes, then ghostty/themes in each XDG data directoryNAME
Kitty~/.config/kitty/themesNAME.conf
Konsolekonsole in each XDG data directoryNAME.colorscheme

An installed theme works by its name alone, for example "Catppuccin Mocha" from Ghostty or Breeze from Konsole. An Afterglow theme with the same name comes first. An afterglow binary in a build directory searches the themes of its source tree before the XDG data directories.

FamilyThemes
Afterglowafterglow-dark, afterglow-light
Ayuayu-dark, ayu-mirage, ayu-light
Catppuccincatppuccin-mocha, catppuccin-macchiato, catppuccin-frappe, catppuccin-latte
Draculadracula
Everforesteverforest-dark, everforest-light
GitHubgithub-dark, github-light
Gruvboxgruvbox-dark, gruvbox-light
Kanagawakanagawa-wave, kanagawa-dragon, kanagawa-lotus
Monokaimonokai
Nordnord, nord-light
Oneone-dark, one-light
Rosé Pinerose-pine, rose-pine-moon, rose-pine-dawn
Solarizedsolarized-dark, solarized-light
Tokyo Nighttokyonight-night, tokyonight-storm, tokyonight-moon, tokyonight-day

The third-party palettes come from iTerm2-Color-Schemes under the MIT license. Supported formats are Afterglow JSON, Ghostty themes, Kitty themes and Konsole color schemes. Afterglow reads its Foreground, Background, Color0 to Color7 and Color0Intense to Color7Intense colors. The intense colors are palette entries 8 to 15. Afterglow has no counterpart for the faint and intense text colors, the wallpaper or the opacity of a Konsole color scheme. An Afterglow JSON theme is one object with color keys. The keys are foreground, background, cursor, cursorText, selectionForeground, selectionBackground, divider and popupBorder. searchMatch, searchCurrentMatch, searchMatchText, visualBell, visualBellIntensity and palette are also keys. A color key can have - or _ between its words, in any mix of upper and lower case, such as popup-border in a Ghostty theme. Afterglow logs other keys in a JSON theme. The colors in a theme have the forms of color values.

Use this value to follow the desktop preference:

{"Colors": {"theme": "light:afterglow-light,dark:nord"}}

The desktop color scheme

Use plasma:NAME to take colors from the desktop color scheme:

{"Colors": {"theme": "plasma:nord"}}
ColorFrom the Plasma color scheme
BackgroundView background ([Colors:View] BackgroundNormal)
TextView text ([Colors:View] ForegroundNormal)
SelectionSelection background and text ([Colors:Selection])
CursorFocus decoration, the accent color ([Colors:View] DecorationFocus)
Text under the cursorView background
DividerDerived from the background and the text
Popup borderDerived from the background and the text
Palette entries 0 to 15Theme NAME

plasma without a name takes the palette from afterglow-dark for a dark color scheme, and from afterglow-light for a light one. Afterglow reads kdeglobals in the XDG configuration directories, as Plasma does. On another desktop, or for a color that kdeglobals does not set, the colors come from the application palette. afterglow mux new has no application palette: such a color stays the color of the theme (see the mux daemon). Afterglow applies a new color scheme while it runs. Each half of a light: and dark: value can also be a plasma: value.

A theme value can also be a file path. Either half of a light: and dark: value can be a path. A relative path starts at the directory of the configuration file. Afterglow monitors that path for changes, including deletion and replacement. A theme file that does not parse keeps its last colors until it parses again.

Color values

A color in Colors or in a theme has one of these forms:

FormExampleValues
A hexadecimal color#1e1e2e, #fff#rgb, #rrggbb, #rrrgggbbb or #rrrrggggbbbb. #fff is white. A theme, but not Colors, can leave out the # of six digits.
An X11 color namered, dark slate grayA name from the X11 color list that Kitty reads, in any mix of upper and lower case. Newer CSS names, such as teal and lime, are not in it.
rgb:r/g/brgb:ff/80/001 to 4 hexadecimal digits for each channel.
rgbi:r/g/brgbi:1/0.5/0A number from 0 to 1 for each channel.
oklch(L C H)oklch(0.7 0.1 200)L is the lightness, C is the chroma and H is the hue.
lab(L a b)lab(50 60 40)CIE LAB with a D50 white point. L is the lightness. a goes from green to red, and b from blue to yellow.

A Konsole color scheme or kdeglobals can also write R,G,B, with each part from 0 to 255. A part outside this range makes the color invalid. Afterglow ignores a fourth part, which is an alpha. Afterglow ignores spaces before and after a color.

OKLCH and CIE LAB are color spaces from CSS Color 4. A step of the same size in their values looks like a change of about the same size. The chroma is how much color there is. The three values of oklch and lab can have spaces or commas between them. The value none is 0. These are the ranges of the values:

ValueRangeOutside the range
rgbi channel0 to 1The nearest limit.
oklch L0 to 1, or 0% to 100%The nearest limit.
oklch C0 to about 0.4, or a percentage of 0.4A negative C is 0. A C larger than 4 is 4.
oklch HDegrees, or a number with the unit deg, rad, grad or turnH counts modulo 360 degrees.
lab L0 to 100, or 0% to 100%The nearest limit.
lab a and bAbout -125 to 125, or a percentage of 125If a or b is outside -1000 to 1000, Afterglow decreases both until the larger is 1000, and keeps their ratio.

Afterglow converts an OKLCH or LAB color to sRGB with 8 bits for each channel. A color outside sRGB gets the gamut mapping of CSS Color 4. This mapping decreases the chroma of the color, and it keeps almost the same lightness and hue. Kitty themes that use these forms work in Afterglow. Some of their colors are not the same as in Kitty: see color escape codes.

A color in Colors or in a theme has no alpha. Afterglow does not accept an eight-digit value such as #1e1e2eff. It also does not accept transparent, in any spelling. Afterglow ignores an alpha in an OKLCH or LAB color, written as / 0.5 or as a fourth value, as Kitty does.

Transparency

SettingDefaultFunction
Window.backgroundOpacity1.0Opacity of the default background, from 0.05 to 1.0. Text stays opaque.
Window.blurfalseBlurs the content behind a translucent background. This requires KWin.

Motion

SettingDefaultFunction
Animation.cursortrueThe cursor glides between cells
Animation.scrolltrueScrolling eases instead of jumping by rows

Animation.cursorCurve and Animation.scrollCurve take a Phosphor curve spec, as Animation.splitCurve does.

An overlay, a program that runs over a pane, fades in and out through Shaders.overlayTransition. Animation.overlayCurve and Animation.overlayDuration set the fade. The fade stops the first time that it reaches its target. A curve that overshoots, such as a spring, does not bounce back.

A popup overlay takes a part of the pane, and the pane stays visible around it.

SettingDefaultFunction
Colors.popupDim0.35Opacity of a black layer over the pane around a popup, from 0 to 1. A value outside this range becomes 0 or 1. A value of 0 turns the darkening off.
Colors.popupBorder""Color of the popup’s border line. An empty value uses the color halfway from the background color to the text color. A theme replaces it, as described in Themes.
Window.popupCornersroundedCorners of the popup’s border: rounded or square.

The title in the border uses the text color.

See shaders for audio, history and visual effects. See bidirectional text for text direction settings.

Mirrored from docs/APPEARANCE.md in the Afterglow repository.