Skip to content

Theming

Wallah colors the transcript, the editor, and syntax-highlighted file output from a single syntect theme. By default it renders Solarized dark, and switches to Solarized light when it detects a light terminal background. You can choose a different theme, fix the light/dark appearance, and tune how colors are kept legible.

Choosing a theme

Configure the theme from config.lua in a reconfigure handler, which fires at startup and on /reload:

agent.on('reconfigure', function()
  agent.configure_theme {
    appearance = 'auto',   -- 'auto' (default) follows the terminal background;
                           -- 'dark' or 'light' fixes it
    contrast = 'auto',     -- 'auto' (default) lifts low-contrast colors to a
                           -- legibility floor; 'off' renders them as-is
    dark = { syntect_theme = 'base16-ocean.dark' },   -- theme for a dark appearance
    light = { syntect_theme = 'Solarized (light)' },  -- theme for a light appearance
    probe_terminal = true, -- query the terminal at startup (see below)
  }
end)

Every field is optional; an omitted field takes its built-in default. A syntect_theme is either a bundled theme name (listed below) or a path to a .tmTheme file. An unknown name is reported against the config line that set it, with a suggestion for the closest bundled name.

The dark and light sub-tables let one config serve both appearances: with appearance = 'auto', Wallah picks the dark theme over a dark terminal and the light theme over a light one. Fixing appearance to 'dark' or 'light' always uses that sub-table and skips the light/dark decision.

Terminal detection and contrast

When the appearance or the contrast pass is left on 'auto', Wallah briefly queries the terminal at startup for its default foreground, its background, and its ANSI palette. The background decides light versus dark; the foreground and palette let the contrast pass measure a color the theme names as a palette index (rather than an explicit value) so it can be kept legible.

The contrast pass, when 'auto', lifts any foreground that falls short of a legibility floor against its background, leaving already-legible colors untouched. Set contrast = 'off' to trust the theme's own colors verbatim.

Some terminals answer no query. In that case Wallah assumes a dark background and leaves palette-indexed colors for the terminal to render. Set probe_terminal = false to skip the query entirely; an 'auto' appearance then renders the dark theme, and the contrast pass measures against a coarse reference instead of the real background.

Bundled themes

List the bundled themes at any time, including when a bad theme name is keeping the config from loading:

$ wa list-themes

The bundled themes are:

  • 1337
  • Catppuccin Frappe
  • Catppuccin Latte
  • Catppuccin Macchiato
  • Catppuccin Mocha
  • Coldark-Cold
  • Coldark-Dark
  • DarkNeon
  • Dracula
  • GitHub
  • InspiredGitHub
  • Monokai Extended
  • Monokai Extended Bright
  • Monokai Extended Light
  • Monokai Extended Origin
  • Nord
  • OneHalfDark
  • OneHalfLight
  • Solarized (dark)
  • Solarized (light)
  • Sublime Snazzy
  • TwoDark
  • ansi
  • base16
  • base16-256
  • base16-eighties.dark
  • base16-mocha.dark
  • base16-ocean.dark
  • base16-ocean.light
  • gruvbox-dark
  • gruvbox-light
  • zenburn

The ansi, base16, and base16-256 themes name their colors as terminal palette indices rather than fixed values, so they follow your terminal's own color scheme.