Adding Providers

Adding a new terminal emulator as a litmus provider involves three pieces: color extraction, capture configuration, and theme registration.

Overview

A provider in litmus needs:

Vendored theme data — the provider’s theme definitions, checked into the repo
Color extractor — code that parses the vendored data into litmus’s provider color format
Capture config generator — code that writes the provider’s config file for headless screenshot capture
Theme mappings — entries in each theme’s definition file mapping to this provider’s theme names

1. Vendor Theme Data

Check the provider’s theme collection into crates/litmus-capture/src/providers/ or a similar location. This is the source of truth for what colors the provider assigns to each theme.

For example, kitty’s themes are vendored from its official themes repo, and wezterm’s are extracted from its built-in theme registry.

Add a module in crates/litmus-capture/src/providers/ that reads the vendored theme data and emits ProviderColors — the standard 21-color palette (16 ANSI + fg/bg/cursor/selection_bg/selection_fg).

The extractor is called by litmus-capture extract-colors and writes .{provider}.toml files:

# AUTO-GENERATED by litmus extract-colors — do not edit
provider = "my-terminal"
source_version = "vendored"

[colors]
background = "#1E1E2E"
foreground = "#CDD6F4"
cursor = "#F5E0DC"
selection_background = "#F5E0DC"
selection_foreground = "#1E1E2E"

[colors.ansi]
black = "#45475A"
red = "#F38BA8"
# ... all 16 ANSI colors

3. Write a Capture Config Generator

Add a capture config generator in the same providers module. This writes a temporary config file that sets:

The theme’s colors
Terminal geometry (80×32 cells, 12pt FiraCode, 1280×960px)
Any provider-specific settings needed for headless operation

See crates/litmus-capture/src/providers/kitty.rs and wezterm.rs for reference implementations.

4. Register the Provider

Register the new provider in crates/litmus-capture/src/providers/mod.rs so the capture tool and color extractor know about it.

5. Add Theme Mappings

For each theme that supports the new provider, add a mapping in the theme definition:

[providers]
kitty = "Catppuccin-Mocha"
wezterm = "catppuccin-mocha"
my-terminal = "Catppuccin Mocha"   # add this

Then run litmus-capture extract-colors to generate the provider color files.

6. Capture and Deploy

# Capture screenshots for the new provider
mise run capture-{provider}

# Build manifest and sync to R2
mise run screenshots-deploy

The web app will automatically pick up the new provider — it discovers available providers from the embedded theme data at compile time.

Litmus