Theming

The client colors the whole interface from a single theme file. Themes use the same TOML format as the Helix editor, so you can reuse existing Helix themes or write your own.

Where themes live

The client looks for themes in two places:

1. its own theme directory, themes/ inside the config directory (~/.config/komp_ac_client/themes/ on a typical Linux setup);
2. the standard Helix theme directory, ~/.config/helix/themes/ (or $XDG_CONFIG_HOME/helix/themes).

On first run the client installs its bundled themes into its own themes/ directory. It only writes a file when it does not already exist, so a theme you edit or replace is never overwritten.

Selecting a theme

Set [colors] theme in config.toml (see Configuration):

[colors]
theme = "gruvbox"

The value is resolved flexibly — a theme name (gruvbox), a filename (gruvbox.toml), or an explicit path are all accepted. The shipped default config uses catppuccin_frappe.

If [colors] is absent altogether, the client falls back to a built-in light theme. A name that cannot be resolved in either theme directory is a startup error, reported as “Failed to load configured theme”.

Theme format

A theme is a TOML file with an optional [palette] of named colors and a set of style scopes that reference them:

[palette]
background = "#1e1e2e"
text = "#cdd6f4"
accent = "#89b4fa"

"ui.background" = { bg = "background" }
"ui.text" = { fg = "text" }
"ui.text.focus" = { fg = "accent" }
"ui.selection" = { bg = "accent", fg = "background" }

Themes may also inherits another theme to reuse its palette and scopes, as the bundled catppuccin_frappe does:

inherits = "catppuccin_mocha"

[palette]
# overrides and additions

Colors can be written as hex (#rrggbb) or as references to [palette] entries. Style scopes set fg, bg, and modifiers (bold, italic, underlined, and so on).

The client maps the Helix UI roles onto its own semantic styles, so the scopes that matter most are:

Scope	What it colors
ui.background	The application background
ui.text	Ordinary text
ui.text.focus	Focused/active text
ui.selection	Selected list items
ui.cursor, ui.cursor.insert, ui.cursor.normal, ui.cursor.select	Cursor per editor mode
ui.statusline, ui.statusline.insert, ui.statusline.normal, ui.statusline.select	The status line
ui.menu, ui.menu.selected	Menus and the selected menu entry
ui.window	Window borders

Unset scopes keep their defaults, so you only need to fill in the roles you care about.

Bundled themes

The client ships 218 themes ported from the Helix ecosystem, installed into themes/ on first run. The collection includes Catppuccin (all variants), Gruvbox, Tokyo Night, Dracula, Solarized, Nord, Rose Pine, Everforest, and many more. Browse the runtime/themes/ directory in the client crate for the complete list.

Adding a custom theme

Add a .toml file to the client’s themes/ directory (or to ~/.config/helix/themes/), then select it by name:

[colors]
theme = "my-theme"

Restart the client to apply the change. Because themes are resolved by name across both directories, name lookups check the client’s themes/ directory first, then the Helix themes directory. To override a bundled theme, edit the file in the client’s themes/ directory; a later upgrade will not overwrite it.

Continue

• Configuration — the [colors] theme setting and the rest of config.toml.