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/.

NamePalette
defaultfollows the terminal: theme_dark on a dark background, theme_light on a light one
kage-shadowdark: ink surfaces with a violet undertone and one warm orange accent
kage-dawnlight: the same roles on a violet-tinted paper
kimi-darkdark: Kimi Code's palette on neutral grey surfaces with a blue accent
kimi-lightlight: 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.

toml
[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 ​

text
/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

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:

toml
# 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.

RoleGroupColors
bgKageNormal bgthe whole-frame canvas behind every block
assistant_fgKageNormal fgassistant text
user_bgKageUserBubble bgprompt bubble fill
user_ruleKageUserRule fgprompt bubble left rule
assistant_ruleKageAssistantRule fgidle left spine on assistant turns
thinking_fgKageThinking fgthinking text
custom_fgKageCustom fgcustom block text
tool_bgKageTool bgtool block fill
tool_result_fgKageTool fgtool result text
tool_error_bgKageToolError bgfailed tool block fill
tool_error_fgKageToolError fgfailed tool result text
tool_pending_bgKageToolPending bgrunning tool block fill
tool_ruleKageToolRule fgtool block left rule
tool_error_ruleKageToolErrorRule fgfailed tool block left rule
tool_pending_ruleKageToolPendingRule fgrunning tool block left rule
muted_fgKageMuted fgsecondary hints and metadata
match_colorKageMatch bgsearch match
selection_colorKageSelection bgvisual selection
selection_fgKageSelection fgselected text
focus_colorKageFocus bgfocused block accent
status_bgKageStatus bgheader row fill
status_dim_fgKageStatus fgheader row text
modeline_bgKageModeline bgcompletion popup and toast fill
modeline_fgKageModeline fgnot painted by the built-in chrome
input_border_normalKageInputBorderNormal fginput rules, normal mode
input_border_insertKageInputBorderInsert fginput rules, insert mode and modeless
input_border_visualKageInputBorderVisual fginput rules, visual mode
input_pill_normal_bg, input_pill_normal_fgKageInputPillNormalemphasized text on the input rule, normal mode (fg only)
input_pill_insert_bg, input_pill_insert_fgKageInputPillInsertemphasized text on the input rule, insert mode (fg only)
input_pill_visual_bg, input_pill_visual_fgKageInputPillVisualemphasized text on the input rule, visual mode (fg only)
input_glyph_fgKageInputGlyph fgprompt glyph
input_placeholder_fgKageInputPlaceholder fgplaceholder text
input_hint_fgKageInputHint fgfooter hint and start card change hints
overlay_fgKageOverlay fgpicker and dialog text
overlay_borderKageOverlayBorder fgpicker and dialog border
overlay_selected_bg, overlay_selected_fgKageOverlaySelectedselected picker row
warning_fgKageWarning fgwarnings
success_fgKageSuccess fgsuccess marks
md_h1_fgKageMarkdownH1 fgmarkdown level 1 headings
md_h2_fgKageMarkdownH2 fgmarkdown level 2 headings
md_link_fgKageMarkdownLink fgmarkdown links
md_code_fgKageMarkdownCode fgmarkdown 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:

GroupDefault linkColors
KageWorkingKageMutedthe working row above the input
KagePlanKageInputBorderInsertthe plan footer chip while plan mode is on
KageInputCommandKageInputGlypha command that opens the draft, such as /model
KageApprovalKageWarningapproval panel rules, title and selected option, and the bullet of a tool call waiting for approval
KageDiffAddKageSuccess+ lines in edit rows and approvals
KageDiffDeleteKageToolErrorRule- lines in edit rows and approvals
toml
[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.

toml
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.

TokenRole
bgApp background
sidebarSidebar and workbench background
surfaceCards, panels and inputs
raisedRaised elements above surface
sunkenPressed-in areas
deepThe deepest level, used behind on-color glyphs
wellWells that read as inset surfaces
fillBarely-there fill for chips and pills
fill_hoverfill one step up, for hover
inkPrimary text
ink_strongEmphasized text
mutedSecondary text
faintTertiary text
ghostQuaternary text and the faintest marks
lineHairline borders
subtleThe faintest fills, below line
line_strongStronger borders, hovered states
hoverRow and control hover fill
selectedSelected row fill
selected_hoverSelected row fill on hover
accentThe warm lantern accent
accent_hoverAccent hover step
accent_softAccent tint background
accent_bdAccent border
okSuccess green
ok_softSuccess tint background
ok_bdSuccess border
ok_inkText on a solid success fill
warnWarning yellow
warn_softWarning tint background
warn_bdWarning border
dangerDanger red
danger_softDanger tint background
danger_bdDanger border
doneSwarm violet
done_softViolet tint background
done_bdViolet border
infoInformational blue
composer_bgThe composer's background
composer_lineThe composer's idle border
composer_focus_lineThe composer's focused border
send_bgThe send button background
send_bg_hoverThe send button hover background
send_iconThe glyph on the send button
send_bg_offThe send button when disabled
send_icon_offThe glyph on the disabled send button
stop_glyphThe stop glyph, a softened danger red
diff_addDiff added lines
diff_add_bgDiff added line background
diff_delDiff deleted lines
diff_del_bgDiff deleted line background
bubbleThe user bubble fill
selectionText selection fill
menuMenus and popovers, slightly translucent
code_inlineInline 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.