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
| Option | Function |
|---|---|
-o Group.key=value | Changes one setting for this launch |
--config | Reads another configuration file. Its directory then holds the themes, shaders, shader-presets and scripts directories |
--class | Sets the Wayland application ID for window rules |
--title | Sets a fixed window title |
--hold | Keeps the window open after an -e program stops |
-e, --execute | Runs the rest of the command line instead of the shell |
-d, --working-directory | Starts in the given directory |
--quick-terminal | Shows or hides the quick terminal |
afterglow -o Font.size=14 -o Colors.theme=afterglow-lightThe 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
| Setting | Default | Function |
|---|---|---|
Font.family | empty | Font family of regular text. Empty uses the desktop’s fixed-width font. |
Font.size | 0 | Size in points, from 4 to 96. 0 uses the size of the desktop’s fixed-width font. |
Font.features | calt, liga | OpenType features in HarfBuzz syntax |
Font.fallbackFamilies | empty | Families that supply missing characters before the system fallback |
Font.symbolMap | empty | Families 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.
| Characters | Code points |
|---|---|
| Box drawing and block elements | U+2500 to U+259F |
| Braille patterns | U+2800 to U+28FF |
| Powerline separators | U+E0B0 to U+E0BF |
| Sextants, smooth mosaics and triangles | U+1FB00 to U+1FB6F, U+1FB9A to U+1FB9F |
| Eighth blocks, quarter blocks, third blocks and half shades | U+1FB70 to U+1FB92, U+1FB94, U+1FBCE, U+1FBCF, U+1FBE4 to U+1FBE7 |
| Diagonal box drawing | U+1FBA0 to U+1FBAE, U+1FBD0 to U+1FBDF |
| Separated quadrants and sextants | U+1CC21 to U+1CC2F, U+1CE51 to U+1CE8F |
| Octants | U+1CD00 to U+1CDE5 |
| Sixteenth blocks and partial quarter blocks | U+1CE90 to U+1CEAF |
Font rendering
| Setting | Values | Default |
|---|---|---|
Font.antialiasing | grayscale, none, rgb, bgr | grayscale |
Font.hinting | none, light, full | light |
Font.gamma | 0.5–3.0 | 1.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.2Subpixel 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:
| Terminal | Directories | File |
|---|---|---|
| Ghostty | ~/.config/ghostty/themes, then ghostty/themes in each XDG data directory | NAME |
| Kitty | ~/.config/kitty/themes | NAME.conf |
| Konsole | konsole in each XDG data directory | NAME.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.
| Family | Themes |
|---|---|
| Afterglow | afterglow-dark, afterglow-light |
| Ayu | ayu-dark, ayu-mirage, ayu-light |
| Catppuccin | catppuccin-mocha, catppuccin-macchiato, catppuccin-frappe, catppuccin-latte |
| Dracula | dracula |
| Everforest | everforest-dark, everforest-light |
| GitHub | github-dark, github-light |
| Gruvbox | gruvbox-dark, gruvbox-light |
| Kanagawa | kanagawa-wave, kanagawa-dragon, kanagawa-lotus |
| Monokai | monokai |
| Nord | nord, nord-light |
| One | one-dark, one-light |
| Rosé Pine | rose-pine, rose-pine-moon, rose-pine-dawn |
| Solarized | solarized-dark, solarized-light |
| Tokyo Night | tokyonight-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"}}| Color | From the Plasma color scheme |
|---|---|
| Background | View background ([Colors:View] BackgroundNormal) |
| Text | View text ([Colors:View] ForegroundNormal) |
| Selection | Selection background and text ([Colors:Selection]) |
| Cursor | Focus decoration, the accent color ([Colors:View] DecorationFocus) |
| Text under the cursor | View background |
| Divider | Derived from the background and the text |
| Popup border | Derived from the background and the text |
| Palette entries 0 to 15 | Theme 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:
| Form | Example | Values |
|---|---|---|
| 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 name | red, dark slate gray | A 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/b | rgb:ff/80/00 | 1 to 4 hexadecimal digits for each channel. |
rgbi:r/g/b | rgbi:1/0.5/0 | A 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:
| Value | Range | Outside the range |
|---|---|---|
rgbi channel | 0 to 1 | The nearest limit. |
oklch L | 0 to 1, or 0% to 100% | The nearest limit. |
oklch C | 0 to about 0.4, or a percentage of 0.4 | A negative C is 0. A C larger than 4 is 4. |
oklch H | Degrees, or a number with the unit deg, rad, grad or turn | H counts modulo 360 degrees. |
lab L | 0 to 100, or 0% to 100% | The nearest limit. |
lab a and b | About -125 to 125, or a percentage of 125 | If 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
| Setting | Default | Function |
|---|---|---|
Window.backgroundOpacity | 1.0 | Opacity of the default background, from 0.05 to 1.0. Text stays opaque. |
Window.blur | false | Blurs the content behind a translucent background. This requires KWin. |
Motion
| Setting | Default | Function |
|---|---|---|
Animation.cursor | true | The cursor glides between cells |
Animation.scroll | true | Scrolling 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.
Popup overlays
A popup overlay takes a part of the pane, and the pane stays visible around it.
| Setting | Default | Function |
|---|---|---|
Colors.popupDim | 0.35 | Opacity 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.popupCorners | rounded | Corners 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.