themes
kage ships four palettes, kage shadow, kage dawn, kimi dark and kimi light, and loads any additional ones you drop into ~/.config/kage/themes/.
| Name | Palette |
|---|---|
default | follows the terminal: theme_dark on a dark background, theme_light on a light one |
kage-shadow | dark: ink surfaces with a violet undertone and one warm orange accent |
kage-dawn | light: the same roles on a violet-tinted paper |
kimi-dark | dark: Kimi Code's palette on neutral grey surfaces with a blue accent |
kimi-light | light: Kimi Code's palette on white |
default asks the terminal for its background color once at startup (the OSC 11 query). When the terminal does not answer, kage reads COLORFGBG, and failing that assumes a dark background. Set any other name to pin a palette.
The kage palettes match the kage-theme Neovim colorscheme and its terminal configs. The kimi palettes take their text and accent colors from Kimi Code's terminal UI and their surfaces from its desktop app.
the default pair
theme_dark and theme_light choose what default shows. They take any bundled or user theme name and fall back to kage-shadow and kage-dawn when unset. The desktop and web client use the same pair for their System choice.
[ui]
theme = "default"
theme_dark = "kimi-dark"
theme_light = "kimi-light"init.lua sets them with kage.opt.theme_dark = "name" and kage.opt.theme_light = "name", and the /settings dialog cycles through them too. A change applies at once while default is the active theme. When the named theme is unknown or fails to load at startup, kage reports the error inline and default shows the kage palette instead. From init.lua or /settings, such a name is rejected.
switching themes
/theme list list bundled and user themes (* marks the active one)
/theme set kage-dawn switch immediately for this session
/theme current show the active theme/theme set applies at once. It does not persist on its own. Set the default in config.toml
[ui]
theme = "my-theme"or use the /settings dialog, which writes only that key back to config.toml. The configured theme is resolved at startup. An unknown name leaves the default palette in place and reports the error inline rather than failing silently.
init.lua sets the theme with kage.opt.theme = "name", which wins over config.toml. Plugins and init.lua can also call kage.theme.set("name"). It switches before it returns and raises on an unknown name. Every switch fires the color_scheme event (see lua config).
writing a custom theme
A user theme is a TOML file at ~/.config/kage/themes/<name>.toml (honoring XDG_CONFIG_HOME). The file name is the theme name. There is no name key. Five top-level keys are accepted, and an unknown key is an error:
# Palette to start from. One of the bundled names. Defaults to
# "default" (kage-shadow or kage-dawn, following the terminal), so you
# only list what you want to change.
base = "kage-dawn"
# See "transparency" below. Defaults to false (fully opaque).
transparent = false
[colors]
bg = "#11131a"
assistant_fg = "#e5e5e5"
focus_color = "#f4a72b"
match_color = "#fbbf24"
[groups]
KageToolError = { fg = "#ff6b6b", bg = "#2a1618" }
KageMarkdownLink = { link = "KageWarning" }
MyAccent = { fg = "#f4a72b", bold = true }
# Palette tokens for the desktop and web client. See "the gui section".
[gui]Every key under [colors] is a role name (full list below). A typo in a role name or an unparseable color aborts the load with a message naming the offender. The theme is not partially applied.
color syntax
[colors] values use ratatui's grammar:
- 24-bit hex:
#rrggbb(e.g.#1f2430) - a named color:
black,red,green,yellow,blue,magenta,cyan,gray,darkgray,lightred,lightgreen,lightyellow,lightblue,lightmagenta,lightcyan,white - a 256-color index as a string:
"244" reset, the terminal's default color
[groups] colors take the same forms except reset. Leave the field out to get the terminal default.
kage reads COLORTERM and TERM once at startup. When the terminal does not advertise truecolor (COLORTERM=truecolor or 24bit, or a TERM ending in -direct), every color is mapped to the nearest entry of the 256-color palette when TERM names 256color, else to the nearest of the 16 ANSI colors.
color roles
[colors] accepts these keys. Anything you omit keeps the value from base. Each role is one color of a highlight group, shown in the second column.
| Role | Group | Colors |
|---|---|---|
bg | KageNormal bg | the whole-frame canvas behind every block |
assistant_fg | KageNormal fg | assistant text |
user_bg | KageUserBubble bg | prompt bubble fill |
user_rule | KageUserRule fg | prompt bubble left rule |
assistant_rule | KageAssistantRule fg | idle left spine on assistant turns |
thinking_fg | KageThinking fg | thinking text |
custom_fg | KageCustom fg | custom block text |
tool_bg | KageTool bg | tool block fill |
tool_result_fg | KageTool fg | tool result text |
tool_error_bg | KageToolError bg | failed tool block fill |
tool_error_fg | KageToolError fg | failed tool result text |
tool_pending_bg | KageToolPending bg | running tool block fill |
tool_rule | KageToolRule fg | tool block left rule |
tool_error_rule | KageToolErrorRule fg | failed tool block left rule |
tool_pending_rule | KageToolPendingRule fg | running tool block left rule |
muted_fg | KageMuted fg | secondary hints and metadata |
match_color | KageMatch bg | search match |
selection_color | KageSelection bg | visual selection |
selection_fg | KageSelection fg | selected text |
focus_color | KageFocus bg | focused block accent |
status_bg | KageStatus bg | header row fill |
status_dim_fg | KageStatus fg | header row text |
modeline_bg | KageModeline bg | completion popup and toast fill |
modeline_fg | KageModeline fg | not painted by the built-in chrome |
input_border_normal | KageInputBorderNormal fg | input rules, normal mode |
input_border_insert | KageInputBorderInsert fg | input rules, insert mode and modeless |
input_border_visual | KageInputBorderVisual fg | input rules, visual mode |
input_pill_normal_bg, input_pill_normal_fg | KageInputPillNormal | emphasized text on the input rule, normal mode (fg only) |
input_pill_insert_bg, input_pill_insert_fg | KageInputPillInsert | emphasized text on the input rule, insert mode (fg only) |
input_pill_visual_bg, input_pill_visual_fg | KageInputPillVisual | emphasized text on the input rule, visual mode (fg only) |
input_glyph_fg | KageInputGlyph fg | prompt glyph |
input_placeholder_fg | KageInputPlaceholder fg | placeholder text |
input_hint_fg | KageInputHint fg | footer hint and start card change hints |
overlay_fg | KageOverlay fg | picker and dialog text |
overlay_border | KageOverlayBorder fg | picker and dialog border |
overlay_selected_bg, overlay_selected_fg | KageOverlaySelected | selected picker row |
warning_fg | KageWarning fg | warnings |
success_fg | KageSuccess fg | success marks |
md_h1_fg | KageMarkdownH1 fg | markdown level 1 headings |
md_h2_fg | KageMarkdownH2 fg | markdown level 2 headings |
md_link_fg | KageMarkdownLink fg | markdown links |
md_code_fg | KageMarkdownCode fg | markdown inline code |
groups
[groups] sets whole highlight groups. It is applied after [colors], and each entry replaces its group, so list both colors of a group that has two. An entry takes fg, bg, bold, italic, underline, dim, reverse and link. A link follows another group and wins over the other fields.
Five chrome groups are not theme roles. Every theme links them to another group, and [groups] can replace them like any other:
| Group | Default link | Colors |
|---|---|---|
KageWorking | KageMuted | the working row above the input |
KagePlan | KageInputBorderInsert | the plan footer chip while plan mode is on |
KageInputCommand | KageInputGlyph | a command that opens the draft, such as /model |
KageApproval | KageWarning | approval panel rules, title and selected option, and the bullet of a tool call waiting for approval |
KageDiffAdd | KageSuccess | + lines in edit rows and approvals |
KageDiffDelete | KageToolErrorRule | - lines in edit rows and approvals |
[groups]
KageApproval = { fg = "#e0af68", bold = true }
KageDiffAdd = { fg = "#9ece6a" }A Kage* name must be one of the groups in the two tables above, and a typo is an error. Any other name defines a group of your own, which plugin spans and slot components can use through hl. The built-in renderer reads only the colors of Kage* groups. Attributes such as bold show where a group is used by name.
init.lua can change groups at runtime with kage.api.hl_set. See lua config.
the gui section
[gui] holds palette tokens for the desktop and web client, which draw their own palette. The terminal ignores the table, so one file themes both.
base = "kimi-dark"
[colors]
focus_color = "#fe8019"
[gui]
accent = "#fe8019"
accent_soft = "#fe80191f"
bg = "#1d2021"
surface = "#282828"The client asks the engine for the themes, so it lists the ones on the machine kage runs on, a remote engine's included. A theme shows in Settings as a card beside the bundled ones. Settings rereads the folder each time it opens, so a new or edited file needs no restart.
The client draws a user theme as its base with the [gui] tokens over it, and takes light or dark from the base. A theme without a base, or with default, starts from kage-shadow on a dark desktop and kage-dawn on a light one. A color is #rrggbb, or #rrggbbaa for one with alpha. An unknown token or an unparseable color is skipped, and the base's value stays.
The System choice draws theme_dark on a dark desktop and theme_light on a light one (see the default pair). Settings sets both from its Appearance page.
| Token | Role |
|---|---|
bg | App background |
sidebar | Sidebar and workbench background |
surface | Cards, panels and inputs |
raised | Raised elements above surface |
sunken | Pressed-in areas |
deep | The deepest level, used behind on-color glyphs |
well | Wells that read as inset surfaces |
fill | Barely-there fill for chips and pills |
fill_hover | fill one step up, for hover |
ink | Primary text |
ink_strong | Emphasized text |
muted | Secondary text |
faint | Tertiary text |
ghost | Quaternary text and the faintest marks |
line | Hairline borders |
subtle | The faintest fills, below line |
line_strong | Stronger borders, hovered states |
hover | Row and control hover fill |
selected | Selected row fill |
selected_hover | Selected row fill on hover |
accent | The warm lantern accent |
accent_hover | Accent hover step |
accent_soft | Accent tint background |
accent_bd | Accent border |
ok | Success green |
ok_soft | Success tint background |
ok_bd | Success border |
ok_ink | Text on a solid success fill |
warn | Warning yellow |
warn_soft | Warning tint background |
warn_bd | Warning border |
danger | Danger red |
danger_soft | Danger tint background |
danger_bd | Danger border |
done | Swarm violet |
done_soft | Violet tint background |
done_bd | Violet border |
info | Informational blue |
composer_bg | The composer's background |
composer_line | The composer's idle border |
composer_focus_line | The composer's focused border |
send_bg | The send button background |
send_bg_hover | The send button hover background |
send_icon | The glyph on the send button |
send_bg_off | The send button when disabled |
send_icon_off | The glyph on the disabled send button |
stop_glyph | The stop glyph, a softened danger red |
diff_add | Diff added lines |
diff_add_bg | Diff added line background |
diff_del | Diff deleted lines |
diff_del_bg | Diff deleted line background |
bubble | The user bubble fill |
selection | Text selection fill |
menu | Menus and popovers, slightly translucent |
code_inline | Inline code fill |
transparency
A terminal grid has no per-cell alpha, so kage cannot dim individual regions. The only meaningful knob is whole-UI:
transparent = false(default): kage paints an opaque base canvas over the entire frame, so nothing of the terminal shows through and there is no patchwork between blocks.transparent = true: kage skips that base, so a blurred or transparent terminal (or your wallpaper) shows through the whole UI. Modal overlays and popups still get an opaque backing so they stay legible over arbitrary terminal content.
There is no per-region opacity. "Make just the conversation see-through" is not expressible in a terminal.