pi-tokenburn

Token usage and cost monitor with budgets, directly in your Pi session.

TypeScript port of the pi collector from tokenburn. Reads Pi's local session logs (~/.pi/agent/sessions/**/*.jsonl). No network, zero prompt tokens. Totals match the tokenburn CLI exactly.

Features

• Status bar: 🔥 1.20M ($52.79) [today], turns red with OVER BUDGET past your limit.
• Report chart: /tokenburn shows the summary plus a vertical column chart (y-axis, budget line, current period marked, over-budget columns in red, peak/avg footer). Daily (14 days), weekly (8 weeks) or monthly (6 months).
• Status line: /tokenburn day|week|month|year|all (or cycle) changes the period shown at the bottom. Charts live under /tokenburn chart <view>.
• Window panel (optional): Today / Week / Month / Total below the editor, with in/out tokens and cost.
• Budgets per day, week and month, in tokens and/or dollars.
• Live: the bottom line updates after every assistant message, not only when a turn ends, at no measurable cost (see Performance).
• Fast: per-file cache keyed on mtime+size. First scan of ~400 MB of sessions takes under a second; refreshes after that take milliseconds. Refresh never blocks the agent loop.

Install

pi install npm:pi-tokenburn
# or
pi install git:github.com/sorinirimies/pi-tokenburn

Commands

Previews

Recorded from a real pi with only this plugin loaded, on synthetic data.

Switch what the bottom line shows (/tokenburn day|week|month|year|all, or cycle):

Charts (/tokenburn chart day|week|month|year|all): the current period is green, with a peak and average footer:

Budgets (/tokenburn budget day 150000, budget week $2.5): the footer turns red past the limit, and the chart draws the budget line with over-budget columns in red:

Live refresh: the footer updates after every assistant message, not only when a turn ends (here a local mock model answers; pi writes the turn to its session log and the counter moves by itself):

Enable / disable: off means off (nothing runs in the background), and charts still work on demand:

Tab-completion uses pi's own menu, with a description for every option:

Tab-completion works for all of these. Unknown input prints usage instead of failing. report <view> is kept as an alias of chart <view>.

Chart example (/tokenburn chart day, with a 150k day budget):

Daily tokens · last 14 days  ┄ budget 150.0k
 291.9k │                                 ██ ▄▄    
        │                                 ██ ██    
        │      ▃▃          ▅▅             ██ ██    
        │┄┄┄┄┄┄██┄┄┄┄┄┄┄┄┄┄██┄┄┄┄┄┄┄▆▆┄┄┄┄██┄██┄▅▅┄
 146.0k │      ██          ██       ██    ██ ██ ██ 
        │      ██    ▂▂ ▇▇ ██       ██ ▇▇ ██ ██ ██ 
        │▁▁    ██    ██ ██ ██       ██ ██ ██ ██ ██ 
        │██ ▇▇ ██ ▅▅ ██ ██ ██ ▃▃ ▁▁ ██ ██ ██ ██ ██ 
        └──────────────────────────────────────────
         26 27 28 29 30 01 02 03 04 05 06 07 08 09 
         Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr 
                                                ▲  
Σ 1.74M ($4.81) · avg 124.4k/day · peak 291.9k (10-07 Wed)

Weeks start on Monday, in local time.

Config

~/.pi/agent/tokenburn.json (written by the commands, editable by hand):

{
  "enabled": true,
  "liveRefresh": true,
  "refreshMs": 750,
  "includeCache": true,
  "chartColor": true,
  "showStatus": true,
  "showWidget": false,
  "statusWindow": "today",
  "budgets": { "dayTokens": 5000000, "weekCost": 50 }
}

• includeCache (default true): count cache read/write tokens in totals, like the tokenburn CLI. Cache reads dominate (often 95%+ of tokens) but are billed far cheaper; set false to budget on input + output only.

• enabled (default true): master switch, same as /tokenburn enable|disable.

• liveRefresh (default true): refresh after each assistant message. false = only when a turn ends. refreshMs (default 750, range 250 to 60000) is the coalescing delay.

• chartColor (default true): color the chart using your pi theme (current period green, over-budget red, budget line yellow). Set false for plain text.

Environment overrides for the session directory: TOKENBURN_PI_SESSIONS, PI_CODING_AGENT_SESSION_DIR, PI_CODING_AGENT_DIR.

Performance

Refreshing is designed to cost nothing you can notice:

• Incremental: pi's session logs are append-only, so after the first parse only the bytes added since then are read (with a cheap integrity check that falls back to a full parse if a file was rewritten or truncated). On a 35 MB active session a refresh after one new message takes ~1.2 ms, down from ~18 ms, and the cost no longer grows with the session.
• Coalesced: a burst of messages triggers one refresh (trailing delay, refreshMs), never two at once.
• Never blocks: refreshes are fire-and-forget and errors are swallowed; the timer is unref'd and cancelled at shutdown.
• Off means off: /tokenburn disable (or "enabled": false) reads no files and starts no timers.

Demo recordings

The GIFs above live in examples/vhs/generated/ and are stored with Git LFS (git lfs install once). They are recorded with VHS from a real pi that loads only this extension, on synthetic data (examples/vhs/fixture.sh: 900 days of made-up sessions in /tmp with deliberately small numbers, and a local mock model for the live-refresh demo), never from real logs, paths or credentials:

just vhs-all          # every tape (examples/vhs/*.tape): needs vhs, ttyd, ffmpeg, pi, bun, python3
just vhs-tape charts  # one tape
just vhs-list         # list the tapes
just demo             # try it yourself in a real pi on the same synthetic data

Security notes

• Local and read-only. It reads pi's session logs and its own tokenburn.json. Nothing leaves your machine: no network, no telemetry, no shell commands, zero runtime dependencies.
• Never breaks pi. Stats refreshes are fire-and-forget and swallow their own errors, so a failure here cannot interrupt a turn or a session start.
• Hand-edited config is sanitised. Unknown or non-numeric budget values are dropped.

Development

bun install
just check          # typecheck + tests + pack check + nushell tests (what CI runs)
just test           # bun test only (with coverage)
just coverage       # tests + a coverage table

Coverage: every bun test collects coverage (bunfig.toml) and fails below 95% lines / 95% functions. CI shows the table on the run page and uploads lcov.info.

CI scripts are nushell (scripts/), the same ones locally and in GitHub / Gitea Actions. just --list shows every task.

Releases (automatic)

So library updates need no human: they are merged once CI passes, built, versioned and published as a patch. A downgrade, a failing check, or a major update stops the chain and waits for review.

Manual release: just bump patch (or minor / major / X.Y.Z), then just release-push.

Secrets (repo settings): NPM_TOKEN is an npm granular access token with publish rights and "bypass 2FA" (required for CI publishing). Optional: GH_PAT (lets a tag push trigger the release itself), GITEA_TOKEN (Gitea).

Commits follow Conventional Commits; the changelog is generated by git-cliff.

Scope

Pi sessions only. For Zed, Claude Code, Codex, Gemini and more, use the Rust tokenburn.

Related plugins

Three small pi extensions that save tokens without adding anything to the system prompt:

pi install npm:pi-edit-first
pi install npm:pi-read-guard
pi install npm:pi-tokenburn

MIT