---
title: Themes
description: Pick one of venom's sixteen colour themes, tweak one, write your own theme file or ship themes in a plugin.
section: plugins
order: 80
audience: [user, builder]
sources: [cli/src/themes.ts, cli/src/theme, docs/configuration.md, examples/themes/my-theme.yaml, docs/venom-theme.schema.json]
features: [plugins.themes]
---

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

```bash
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

```yaml
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

```yaml
# ~/.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:

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

## Related

- [Write a plugin](/docs/plugins/writing.md)
- [Charts](/docs/plugins/charts.md) (chart series use `chart.1` to `chart.6`)
