# pi-sysmon
**bottom-style braille line charts inside [pi](https://github.com/earendil-works/pi)**
CPU · Memory · Network · Tokens — real-time history curves drawn with braille dot-matrix characters
[](#testing)
[](LICENSE)
The default four charts at 150 columns wide. Curves are drawn with braille characters,
y-axis tick marks are overlaid inside the plot area, and time labels are embedded in the bottom border.
When the terminal narrows, the charts go 2×2, and narrower still, 1 column stacked. The breakpoint
is 96 columns: ≥ 96 gives four charts in a row (the screenshot above), < 96 drops to 2×2 (this one
is 95 columns). At the same width, bottom would crush all four charts into one row (about 16 columns
each), making the curves unreadable.
### The two directions of the Tokens chart
```
┌ Tokens ─ ~58t/s ·92% ⌀87% ↑5.9k ↓60 R2.7k ─┐
```
The readings use the same convention as pi's own status bar (`↑` upstream input / `↓` downstream
output / `R` cache reads), so the two can be compared directly. A few details:
- **The main curve only plots the downstream rate.** The two directions have completely different shapes
over time (upstream is one bulk upload; downstream streams token by token — a measured ratio of
about 516:1), so plotting them on the same axis would flatten downstream to 0.2% of the height.
- **`~` only appears on the rate** — it's estimated from streaming deltas; the cumulative figures
come from the provider's exact `usage`, so they carry no `~`. Which number to trust is obvious at a glance.
- As the block narrows, segments are dropped by importance: rate → instantaneous hit → cumulative
hit → upstream → downstream → cache reads.
### Cache hit rate: the second curve
Cached prompt tokens are billed far cheaper than fresh input, so the hit rate is the one number
that says whether the cache is actually working. The Tokens block shows it two ways:
- **`⌀N%` — session-cumulative hit rate** (the yellow curve). `⌀` reads as "average"; the value is
recomputed from the session's running totals every time a message lands, so the curve is a
staircase — honest, since the underlying numbers are exact provider-reported totals with no
sub-frame information to draw.
- **`·N%` — instantaneous hit rate** (title bar only). The last turn's own
`cacheRead / (cacheRead + input)` ratio; this is the actionable one; the cumulative average
would hide a cache-missing turn for a long time.
The yellow curve has its **own fixed 0–100% scale**, pre-mapped onto the TPS axis and excluded
from the y-scale: a 90% hit rate always renders as 90% of the plot height, even while a
3000 t/s streaming spike pushes the TPS axis top higher. The gutter still shows TPS only — the
color binding (yellow curve ⇄ the `⌀` readout) is what tells the two apart.
Both readouts appear only once the provider has reported a cache read (`R`); sessions that never
touch the cache degrade to the previous single-curve block unchanged. In `line` mode the same
`·N%`/`⌀N%` readouts appear (gated identically), and the token group now sits before NET in the
importance order — when the line runs out of room, whole groups are dropped from the tail, and
the token readout is far less recoverable from elsewhere on screen.
## Installation
### Install with pi (recommended)
```bash
# latest release from npm
pi install npm:pi-sysmon
# or pin an exact version
pi install npm:pi-sysmon@0.4.0
# or straight from git
pi install git:github.com/zzjcool/pi-sysmon
```
Restart pi and the curves appear — **enabled by default**. Update later with
`pi update npm:pi-sysmon`, remove with `pi remove npm:pi-sysmon`.
### From a git clone: single file (simplest manual install)
```bash
git clone https://github.com/zzjcool/pi-sysmon && cd pi-sysmon && npm install
npm run build:single # produces dist/pi-sysmon.ts
cp dist/pi-sysmon.ts ~/.pi/agent/extensions/pi-sysmon.ts
```
### From a git clone: directory form (multiple files)
```bash
git clone https://github.com/zzjcool/pi-sysmon
cp -r pi-sysmon ~/.pi/agent/extensions/pi-sysmon
```
> ⚠️ The directory form **must live in a subdirectory**. pi's auto-discovery treats every `.ts`
> directly under `extensions/` as an extension; laying out multiple files flat would make
> `braille.ts` get loaded as an extension and break the whole load.
### Try it without installing
```bash
pi -e npm:pi-sysmon
```
## Usage
```text
/sysmon toggle on / off (**this session only**)
/sysmon on | off explicit on / off (this session only)
/sysmon global on | off default on/off for **future** sessions (also applies to this one)
/sysmon chart chart mode (default)
/sysmon below|above place the charts / line below (default) / above the editor (persisted)
/sysmon line single-line text mode (the `CPU … TOK …` line; alias: `status`)
/sysmon footer replace the entire footer with the charts (can be taller than widget mode)
```
`chart` / `line` are **mutually exclusive display modes** (naming a mode switches to it and turns the monitor on — it never turns the monitor off); `on` / `off` / `above` / `below` are orthogonal to the mode.
### Click to switch modes (fullscreen TUI only)
In pi's **fullscreen** TUI mode (`--tui-mode fullscreen`, or **TUI mode** in `/settings`),
the panel shows a small clickable `[line]` / `[chart]` chip at its bottom-right —
one click switches between chart and line mode, no command needed:
```text
┌ CPU ─ 12% ───────────────────────┐
│ ⡿⢸⣿⡇ ... │
└ 60s ──────────────────────── 0s ┘
[line]
```
- The click runs the **same path** as `/sysmon chart` / `/sysmon line` — the
mode switch is persisted as a global display preference, and the session's
on/off state is never touched.
- In `line` mode the chip shares the text row (the row stays exactly 1 line
tall — the chip borrows its columns from the metrics, which drop whole
groups from the tail as usual).
- In fullscreen the chart pays for the chip row **out of its row budget**, so
the panel never grows past `WIDGET_MAX_ROWS`.
- Clicks outside the chip are not consumed: drag-to-select text over the panel
keeps working exactly as before.
- `regular` TUI mode (the default) never captures mouse input — the terminal
owns the scrollback there — so no chip is rendered and the panel behaves
exactly as before. Use `/sysmon chart | line` instead.
Why no hover highlight on the chip: under tmux/zellij/screen pi only enables
button-motion mouse reporting (no `move` events), so the chip must read as
clickable without any hover feedback.
### Session scope vs global scope
`/sysmon on|off` is **session-scoped**: it is stored in that session's own entry list, so
`/resume` brings the switch back exactly as you left it, while **other sessions and future
runs are unaffected**. Off in one project stays off in that session only.
`/sysmon global on|off` writes the **default for every new session** to
`