Themes

volee draws with semantic roles, such as state.needs_input or diff.added, never with fixed colors. A theme maps those roles to colors.

Pick a theme

volee ships with five themes:

From the interface

Press Space t, or type :theme, to open the theme picker at the bottom right of the screen. It lists the built-in themes, then your own from ~/.config/volee/themes. Moving in the list applies each theme at once, so you see it on your own agents before you decide.

• Enter keeps the theme and saves it as [tui] theme in your configuration. The rest of the file, comments included, is left as it was.
• Esc closes the picker and brings back the theme you had.

From the command line

volee --theme <name> opens the interface with that theme for this run. It does not change the configuration, and it wins over [tui] theme. An unknown name is refused with the list of the themes that exist.

volee --theme catppuccin-latte
volee demo --theme catppuccin-latte

In the configuration

[tui]
theme = "catppuccin-latte"

volee looks for a theme in ~/.config/volee/themes/<name>.toml first, then among the built-in themes.

When nothing is set

With no --theme and no [tui] theme, volee looks at your terminal: it asks for the background color and uses catppuccin-mocha on a dark background and catppuccin-latte on a light one. When the terminal does not answer (some multiplexers and remote sessions), it reads the COLORFGBG variable, and when that is missing too it keeps catppuccin-mocha. The guess is only made when the output is a terminal, and never waits more than a moment. Set a theme to turn it off.

The order is: --theme, then [tui] theme, then the guess, then catppuccin-mocha.

volee uses 24-bit colors when the terminal announces them in COLORTERM (truecolor or 24bit), and otherwise replaces each color by the nearest one of the 256-color palette. The terminal theme uses only the 16 colors your terminal lets you configure.

The background

volee shows your terminal’s own background under its text, whatever the theme: its color, and its transparency or blur when your terminal has some. The theme colors the text, the borders and what fills a cell on purpose, such as the selected row, a state badge or a notice.

To have the theme’s own background color instead (the background role of the theme):

[tui]
background = "theme"

The theme picker shows each theme over the background you chose. A theme made for a light background reads badly on a dark terminal, and the other way round: when nothing is set, volee picks the flavor that matches your terminal (above).

Write a theme

A theme is a TOML file with an optional parent, a palette of named colors, and the roles:

# ~/.config/volee/themes/dusk.toml
inherits = "catppuccin-mocha"

[palette]
ember = "#ff9e64"

[roles]
"state.needs_input" = { fg = "ember", modifiers = ["bold"] }
"role.worker" = "sky"
edge = "#3b4261"

• inherits starts from another theme (yours or a built-in one). A theme may inherit from the built-in theme of the same name to change only a few roles of it.
• [palette] names colors. A palette entry of the child replaces the parent’s, and every role that uses it follows: that is how the Catppuccin flavors share one set of roles.
• [roles] gives each role a color (a plain string sets the foreground) or a style: { fg = "...", bg = "...", modifiers = [...] }. Modifiers are bold, dim, italic, underlined, reversed and crossed-out.
• A color is a palette name, an ANSI name (red, light-blue, dark-gray…), reset for the terminal’s default, #rrggbb, or a 256-color index.
• A role a theme does not set falls back to its parent role (state.working falls back to state), then to the terminal’s default style. Unknown roles are ignored, so a theme keeps working with older and newer versions of volee.

Roles