Quickstart · plottypus

Run it:

plottypus

It starts sampling every 500 ms and picks a layout for your window size. Nothing is written to disk until you change a setting.

What you are looking at#

A window at least 60 columns by 16 rows opens on Work: the machine on the left (cpu, gpu, mem, heat, net, power), the process table on the right. A smaller window opens on Glance, one column of graphs with no process table. v switches between them. See Surfaces.

Every panel title carries its live numbers. The body is a braille graph of the last two minutes, and every graph on screen shares that one clock, so a spike in cpu lines up with the spike in power under it.

The last row is the footer:

text

 plottypus ≡  ? help  f filter  x kill  s settings  q quit      All normal    79% ▼ 7.3W 7h49m  7.3W  ● 500 ms

From the left: the main menu, the keys that work where you are, the verdict, then the power source and battery (laptops only), whole-system watts and the sampling rate. When the window narrows, the least important readings drop out whole; numbers are never cut in half.

The first keys#

Key	Does
`?`	Every key for where you are
`/` or `f`	Filter processes by name as you type
`enter`	Open the selected process’s details, or expand the focused panel
`tab`, `→` / `shift-tab`, `←`	Move focus between panels
`e`	Expand or collapse the focused panel
`x`	Ask the selected process to quit (TERM), after a confirmation
`s`	Settings
`p`	Pause: sampling stops completely until you press it again
`q`	Quit (inside an overlay it only closes the overlay)

Using htop or btop muscle memory? PLOTTYPUS_KEYS=htop plottypus or PLOTTYPUS_KEYS=btop plottypus, or pick the profile in settings → keys. The full tables are on Keys.

The mouse#

Click a process to select it and double-click to open it. Click a column header to sort by it; click again to reverse. Click a panel to focus it, its [↗] corner to expand it and [×] to close. Drag the gutter between the machine and the process table to resize. Every hint in the footer is a button. --no-mouse turns all of it off.

Five presets#

1 to 5 switch to a ready-made look. A preset turns the gpu, network, disk, heat and per-core switches on if listed and off if not, and sets the surface, the sort and zen mode. The power box is left as it is. The change is saved like any other setting.

Key	Preset	Turns on
`1`	silicon	gpu, heat, per-core bars
`2`	ml	gpu; processes sorted by memory
`3`	laptop	heat, per-core bars
`4`	sre	network and disk, always on Work
`5`	ricer	every panel on Glance, zen mode on

Z toggles zen mode on its own: graphs only, no footer, no scale labels.

Without a terminal#

plottypus --diagnose                     # one verdict and its evidence
plottypus --json | jq .cpu_power         # one sample as JSON
plottypus --json-stream -i 1s --count 10 # NDJSON, one line per second

See JSON output and Diagnose and doctor.

Flags#

text

-i, --interval <TIME>  Sampling interval: 250, 250ms, 1s, 1.5s (100ms..60s)
    --theme <NAME>     Colour theme (auto, billabong, paper, terminal, ...)
    --surface <NAME>   Start on the work or glance surface
    --no-mouse         Do not capture the mouse
    --config <PATH>    Read preferences from PATH
    --print-config     Print the effective preferences and exit
    --json             Print one JSON sample and exit
    --json-stream      Print one JSON sample per interval (NDJSON)
    --count <N>        Stop --json-stream after N samples
    --procs <N>        Processes in JSON output (default 10)
    --diagnose         Print a one-line verdict with its evidence
    --demo             Play a canned 60 s session instead of this Mac
-h, --help             Print this help
-V, --version          Print the version

--flag=value works too. An unknown flag prints the usage and exits with status 2, and so does starting the dashboard without a terminal attached (one line on stderr, no escape codes). --demo combines with every mode except doctor and license.