Themes

The board is light or dark out of the box and follows your system. If you would rather it matched your editor and terminal, it takes a theme. Every theme is a short JSON file in ~/.config/kelpie/, next to your config, and kelpie manages them all the same way: the two it comes with, the ones you download and the ones you write.

Picking one

Open the board’s experiments menu and choose Settings. Under Appearance, every theme file in ~/.config/kelpie/ is a card drawn in its own colours, and a click applies it. none is the board’s own light and dark. A file kelpie cannot use is shown as a broken card with the reason.

Or name the file in ~/.config/kelpie/config.json, without the .json:

{
  "theme": "catppuccin"
}

The theme colours the whole board: the session list, the Chat tab, the Terminal view’s sixteen ANSI colours and the Diff tab’s added and removed lines. While a theme is set, the light and dark button in the masthead is hidden, since the theme decides. Set "theme" back to "" for the board’s own light and dark. An open board follows either change within a second, without a reload.

The ones kelpie comes with

When a board starts and ~/.config/kelpie/ holds no theme yet, kelpie puts catppuccin.json and nord.json there. From then on they are your files: edit them and kelpie never overwrites your changes, delete one and it stays deleted, unless theme still names it. If you already keep themes of your own there, save catppuccin.json or nord.json next to them.

To download

everforest.json

everforest-light.json

Save one in ~/.config/kelpie/ and it is a card in Settings. Everforest is the palette by sainnhe, MIT licensed.

Your own

A theme is a JSON file with a base of "light" or "dark" and a colors object. The base supplies every colour the file leaves out, so a theme can be three lines or forty:

{
  "base": "dark",
  "colors": {
    "ground": "#1e1e2e",
    "accent": "#cba6f7",
    "s-needs": "#fab387"
  }
}

Save it as ~/.config/kelpie/<name>.json, with a name of lowercase letters, digits and dashes, and reload Settings to see its card. A file kept anywhere else works too, by its path in theme, ~ included. An agent can write one for you: kelpie’s agent skill tells it where and in what shape. Colours are hex (#rgb to #rrggbbaa) or rgb() and rgba(). A file kelpie cannot use, whether bad JSON, a missing base or a value that is not a colour, is ignored as a whole, and the board names the problem as a setup check instead of drawing half a theme.

The quickest start is a copy of nord.json or catppuccin.json, which set every name below.

The colour names

Name	What it colours
ground, surface, surface-2	The page, the panels and rows on it, and what lifts off those: hovered menu items and options.
ink, ink-soft, muted	Titles, body text, and the quiet text: times, repo names, hints.
rule, rule-soft, edge	Dividers, the fainter ones inside menus and lists, and the strongest lines, like the masthead’s separators.
accent, accent-soft	Links, the selected tab and focus; the soft one tints notices and hovered chips.
s-needs, s-running, s-snoozed, s-closed	Each group’s colour: its heading, its row stripe and its state chips. Each has a -bg twin for its tinted background.
s-fail	Failing checks, refusals, and a dev server that has stopped.
term-ground, term-ink, term-0 … term-15	The Terminal view: its background, default text, and the sixteen ANSI colours in the usual order, black to bright white.
diff-add-bg, diff-add-ink, diff-add-gutter	Added lines in the Diff tab: the line, its text and the line-number gutter.
diff-del-bg, diff-del-ink, diff-del-gutter	The same for removed lines.