# Themes and glass

Canonical: https://plottypus.com/docs/themes

Last updated: 2026-09-23

> How plottypus builds its colours from your terminal's palette, the ten built-in themes, glass mode for translucent windows, extra contrast, NO_COLOR and tmux.

## `auto`: your terminal's own colours

The default theme is `auto`. At startup plottypus asks the terminal for its colours in one batch: OSC 10 (foreground), OSC 11 (background) and OSC 4 for the sixteen ANSI colours, then a DA1 query so it knows when the replies are done. It waits at most 120 ms, then carries on either way. A reply that straggles in later is swallowed instead of being read as keystrokes.

When the terminal answers, each panel keeps its own hue family in your terminal's shades: cpu green, gpu violet, memory teal, network blue, disk gold, heat orange. Every colour is then checked against your background for contrast and lightened or darkened until it passes. On Ghostty's Kanagawa Dragon at 75% opacity, for example, cpu comes out as `#8fc98f`.

When the terminal does not answer, `auto` falls back to `COLORFGBG`, then to a dark background. It picks **paper** on a light background and **billabong** on a dark one; **terminal** on a 16-colour terminal; **monotreme** with no colour at all.

The query is skipped over ssh (`SSH_TTY` or `SSH_CONNECTION` set), when stdin or stdout is not a terminal, with `TERM=dumb`, and with `NO_COLOR` set. Over ssh a late reply could arrive as keystrokes, so plottypus does not risk it; set `PLOTTYPUS_THEME` there.

Amber and coral are reserved for state: warm temperatures, throttling, memory pressure, a process armed to be killed. A calm Mac is a cool-toned screen.

## Built-in themes

| Theme | Pick it for |
| --- | --- |
| `auto` | Your terminal's own palette (the default) |
| `billabong` | Dark terminals |
| `paper` | Light terminals |
| `okabe` | Red-green colour blindness (Okabe-Ito hues) |
| `monotreme` | One grey ink; only alarms carry colour |
| `terminal` | Your own 16-colour scheme: ANSI colours only, no truecolor needed |
| `catppuccin-mocha` | Catppuccin Mocha |
| `tokyo-night` | Tokyo Night |
| `nord` | Nord |
| `kanagawa` | Kanagawa (Dragon) |
| `gruvbox-dark` | Gruvbox dark |

Names forgive case, spaces and underscores, and a few aliases work: `catppuccin`, `mocha`, `tokyonight`, `tokyo`, `mono`, `ansi`, `dragon`, `kanagawa-dragon`, `gruvbox`.

Three ways to pick one:

```sh
plottypus --theme paper            # this run only
PLOTTYPUS_THEME=nord plottypus     # wins over the config file
```

```toml
theme = "kanagawa"                 # config.toml
```

`T` cycles themes live, and settings → appearance previews each one in its own colours.

## Glass: translucent and blurred windows

Ghostty, among others, draws a cell with an explicit background colour at full opacity even when the window is translucent. A selected row then becomes a solid slab across your wallpaper. Glass mode fixes that: plottypus paints **no cell backgrounds at all**, marks the selected row with a gutter bar and bold text instead, and brightens frames and dim text so they stay readable over whatever is behind the window.

`glass = "auto"` (the default) turns it on when your terminal's own config file sets a background opacity below 1:

| Terminal | Setting read | Files |
| --- | --- | --- |
| Ghostty | `background-opacity` | `$XDG_CONFIG_HOME/ghostty/config`, `~/Library/Application Support/com.mitchellh.ghostty/config` and `config.ghostty`; the last one that sets it wins |
| kitty | `background_opacity` | `$XDG_CONFIG_HOME/kitty/kitty.conf` |
| Alacritty | `[window] opacity` or `window.opacity` | `~/.alacritty.toml`, `$XDG_CONFIG_HOME/alacritty/alacritty.toml` |

Other terminals (WezTerm, iTerm2) are not read. Set it yourself:

```toml
glass = "on"          # assumes 75% opacity if the terminal's config says nothing
```

or, for one run, `PLOTTYPUS_GLASS=on`, `off`, or an opacity such as `PLOTTYPUS_GLASS=0.8`. The environment variable wins over the setting.

Ghostty `config-file` includes and per-theme overrides are not followed yet.

## Extra contrast

`extra_contrast = true` (settings → appearance) raises every contrast floor: dim text, hints and frames get brighter. Use it over a bright or busy wallpaper, or on a projector.

## Colour depth

plottypus decides between 24-bit, 256 and 16 colours from `COLORTERM`, `TERM_PROGRAM` and `TERM`. 256- and 16-colour terminals get the nearest colours from the same theme, lowered once per frame.

- **Terminal.app** has 24-bit colour from macOS 26. On older macOS it gets the 256-colour version.
- **Force it** with `PLOTTYPUS_COLORS=truecolor`, `256`, `16` or `none` if the guess is wrong.

## `NO_COLOR`

With `NO_COLOR` set to anything non-empty, plottypus uses **monotreme** and draws with attributes only (bold, dim, reverse). Naming a theme with `PLOTTYPUS_THEME` overrides it.

## tmux

Inside tmux, `TERM` is usually `tmux-256color`, so plottypus uses 256 colours unless `COLORTERM=truecolor` reaches it. If your outer terminal and tmux both do 24-bit colour, `PLOTTYPUS_COLORS=truecolor` turns it on.

Palette detection works when tmux answers or passes on the colour queries. If `auto` picks the wrong light or dark theme inside tmux, name one: `PLOTTYPUS_THEME=paper`.

## Icons

`icons = "nerd"` (or `PLOTTYPUS_ICONS=nerd`) puts Nerd Font glyphs in panel titles; it needs a Nerd Font. `none` keeps titles to plain ASCII marks. The default uses ordinary Unicode.