plottypusInstall

Reference

Troubleshooting

Start with plottypus doctor. It shows what your Mac exposes and which collectors work, and it is what we will ask for in a bug report.

The graphs look like dots, boxes or question marks#

The graphs are braille characters (U+2800 to U+28FF), and the panels use rounded box-drawing corners. Your font has to have both. JetBrains Mono, SF Mono, Berkeley Mono and Iosevka do. If a font lacks braille, the terminal substitutes another font or draws empty boxes.

Pick a monospace font with full braille coverage and restart plottypus. For panel-title icons, icons = "nerd" needs a Nerd Font; the default needs none.

The colours are wrong, or unreadable#

  • Too dark or too light for your background: auto guessed the wrong background. Name a theme: PLOTTYPUS_THEME=paper on a light terminal, PLOTTYPUS_THEME=billabong on a dark one. T cycles them live.
  • Washed-out, or colours look posterised: the colour-depth guess is wrong. Force it with PLOTTYPUS_COLORS=truecolor (or 256, 16).
  • Solid dark bars on a translucent window: turn on glass, glass = "on" or PLOTTYPUS_GLASS=on. plottypus reads the opacity from Ghostty, kitty and Alacritty configs, but not WezTerm or iTerm2.
  • Hard to read over a busy wallpaper: extra_contrast = true.
  • No colour at all: check for NO_COLOR in your environment. It switches to monotreme with bold, dim and reverse only.

See Themes and glass.

Terminal.app#

Terminal.app has 24-bit colour from macOS 26, and plottypus uses it there. On an older macOS it falls back to 256 colours, which works but looks flatter.

tmux#

It works. Two things to know:

  • tmux usually sets TERM=tmux-256color, so plottypus uses 256 colours. If your outer terminal and tmux both handle 24-bit colour, set PLOTTYPUS_COLORS=truecolor.
  • The palette query for auto only works if tmux answers or passes on OSC 10/11/4. If the theme comes out wrong, set PLOTTYPUS_THEME.

Copying a pid or command (y/Y in the details card) uses OSC 52, which tmux forwards with set -g set-clipboard on.

ssh#

plottypus runs fine over ssh; it reads the Mac it runs on. It does not query the terminal’s palette over ssh (a late reply could arrive as keystrokes), so auto falls back to COLORFGBG and then dark. Set PLOTTYPUS_THEME in the remote shell if you want something else.

“the dashboard needs a terminal”#

text
plottypus: the dashboard needs a terminal on stdin and stdout; try --json, --diagnose or --help

You started the dashboard with stdin or stdout redirected (a pipe, a cron job, an editor’s task runner). It exits with status 2. Use --json, --json-stream or --diagnose there.

A process shows —#

That process belongs to another user (root, _windowserver, …). macOS refuses an ordinary user its CPU, memory, threads and energy (EPERM), and plottypus shows — instead of inventing 0. Its CPU still counts in the machine total. sudo plottypus shows those numbers. Details: Processes.

“owned by root: needs admin” when I press x#

Same cause: you can only signal your own processes without sudo. plottypus checks before it arms the action, so nothing is sent.

No fan panel, no battery, no heat panel#

That is your Mac, not a bug:

  • MacBook Airs are fanless, so there are no fans to show.
  • Desktops (Mac mini, Studio, iMac) have no battery.
  • A few Macs expose no temperature sensors to user space; the heat panel hides there.

plottypus doctor shows the SMC key counts (temperature, fan, power) and which collectors report absent.

CPU, ANE or DRAM watts come and go#

On macOS 27 the IOReport energy counters for CPU, ANE and DRAM publish in batches, seconds to minutes apart. plottypus holds each value for up to 10 seconds, marked ≈ with its age, then shows the rail as absent until the next batch. On a Mac without SMC CPU rails (everything except the M5 Pro so far), CPU watts can be absent for long stretches. The system figure (PSTR) and GPU watts do not depend on those batches. See Power and battery.

The CPU number is lower than Activity Monitor’s#

The cpu headline is frequency-weighted: a core busy at a low clock counts for less. Activity Monitor’s number shows as busy beside it when the two differ by more than 10 points. The process table uses the same per-core unit as Activity Monitor. See Panels → cpu.

Settings are not saved#

  • The footer says config is read-only (not saved): the file or its directory is not writable. plottypus will not force it.
  • Your file failed to parse: plottypus copied it to config.toml.bak and ran on defaults. Fix the file, or delete it to start clean.
  • You launched with --config <path>: changes go to that file.

The first second shows …#

Rates (CPU, network, disk, per-process CPU) need two samples. Until then plottypus shows … rather than a zero it did not measure. Cluster clocks need a first IOReport window, about a second.

Still stuck#

Send the output of plottypus doctor, your terminal and macOS version, and what you expected to see, to the contact address at the end of the EULA. Anything security-related goes by the rules on Security.