plottypusInstall

Using it

Themes and glass

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.