Skip to content
Docs menu

Themes

Pick one of venom's sixteen colour themes, tweak one, write your own theme file or ship themes in a plugin.

View .md

Every colour venom draws (the HUD, call meter, agents panel, charts, warnings) and pi's own UI (messages, Markdown, code, diffs, dialogs) comes from one theme. The default setting, auto, picks venom-night on a dark terminal and venom-light on a light one.

Quick start

venom theme list               # the themes, where each comes from, the one in use
venom theme preview --all      # each theme drawn: logo, HUD, agents panel, meter, code
venom theme show amber-night   # its palette and every contrast ratio

In a session, /theme opens a picker (arrows recolour the screen as you move, typing filters, Enter saves ui.theme to ~/.venom/config.yaml, Esc puts the old one back). /theme <name> and /theme next switch and save at once; the leader then t (ctrl+g t) is /theme next. /theme auto saves auto. A project's venom.yaml that sets ui.theme wins over yours.

Commands

Command What
venom theme list every theme, its source, the one in use, and load problems
venom theme show <name> palette and contrast ratios
venom theme preview [name], venom theme preview --all draw one theme, or all of them
venom theme tokens every token a theme can set
venom theme new <name> [--base <theme>] [--light|--dark] [--project] write a commented starter to ~/.venom/themes/<name>.yaml (or .venom/themes/ with --project); never overwrites
venom theme check <file> validate one file and print every contrast ratio against its floor (exit 1 if it would not load)
venom theme schema the theme file's JSON Schema

Built-in themes

Ten dark: venom-night (default dark), venom-dusk, amber-night (no blue in any colour), high-contrast, colorblind (Okabe-Ito hues), venom-classic (the look before themes), low-glare (alias calm), deep-sea (sea, ocean), forest-night (forest), obsidian (oled). Six light: venom-light (light), sepia-paper (sepia, paper), daylight, high-contrast-light (hc-light), colorblind-light (cb-light), sage-light (sage).

Every theme meets 4.5:1 contrast for text, 3:1 for glyphs and UI colours, and 7:1 for body text on dark themes, and none uses pure white on pure black. Colour is never the only signal: every state also has a glyph or a word. For long sessions try low-glare or sepia-paper; for low vision high-contrast or high-contrast-light; for a red-green colour deficiency colorblind or colorblind-light.

Themes do not paint the terminal background; set your terminal's background near the theme's bg (venom theme show names it). With 256 colours each colour maps to the nearest xterm entry, with 16 to the terminal's palette, and NO_COLOR turns colour off.

Configuration

ui:
  theme: venom-dusk          # a theme name, or auto (default)
  theme_overrides:
    accent: "#7aa2f7"
    role.code: "#9ece6a"
Key Type Default What
ui.theme string auto the theme
ui.theme_overrides map of token to #rrggbb or a palette name none single colours on top of the theme

Write a theme

# ~/.venom/themes/my-theme.yaml
name: my-theme            # lowercase letters, digits, dashes
base: venom-night         # optional: start from a theme
appearance: dark          # dark | light
description: venom-night with a blue accent
palette:                  # bg surface overlay fg muted dim border red orange yellow green cyan blue purple pink accent ok warn crit
  bg: "#1a1b20"
  accent: "#7aa2f7"
tokens:
  role.code: "#9ece6a"
  hud.model: accent

Every token derives from the 19 palette colours, so a theme can be just a palette. venom's own tokens include bg, badge.fg, level.ok|warn|crit, role.* (agents panel badges), mode.* (permission mode in the HUD), hud.*, leader, logo.*, chart.1 to chart.6 and color.*; pi's tokens (text, muted, accent, md*, syntax*, toolDiff*) colour pi's UI.

Themes load in this order: built-in, plugins, yours in ~/.venom/themes/ (may replace a built-in of the same name), the project's in .venom/themes/. Themes are data, so a project's load without the trust prompt, but they are validated strictly: known keys only, #rrggbb colours, 64 KiB per file, text at 4.5:1 or better, bg matching appearance. A project theme cannot take a name you already have. Problems are listed once at session start and by venom theme list.

Themes in a plugin

A plugin ships themes in themes/ or in the directories its manifest lists:

{ "name": "nightfall", "venom": { "themes": ["./colours"] } }