pi-tokenburn 0.5.0 โ†’ 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +83 -17
  2. package/extensions/tokenburn.ts +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,11 +1,18 @@
1
1
  # pi-tokenburn
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/pi-tokenburn.svg)](https://www.npmjs.com/package/pi-tokenburn)
4
+ [![npm downloads](https://img.shields.io/npm/dm/pi-tokenburn.svg)](https://www.npmjs.com/package/pi-tokenburn)
5
+ [![CI](https://github.com/sorinirimies/pi-tokenburn/actions/workflows/ci.yml/badge.svg)](https://github.com/sorinirimies/pi-tokenburn/actions/workflows/ci.yml)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+
3
8
  Token usage and cost monitor with budgets, directly in your [Pi](https://github.com/earendil-works/pi-coding-agent) session.
4
9
 
5
10
  TypeScript port of the pi collector from [tokenburn](https://github.com/sorinirimies/tokenburn).
6
11
  Reads Pi's local session logs (`~/.pi/agent/sessions/**/*.jsonl`). **No network, zero prompt tokens.**
7
12
  Totals match the `tokenburn` CLI exactly.
8
13
 
14
+ <img src="examples/vhs/generated/overview.gif" alt="pi-tokenburn: the live footer counter, a report with a daily chart, switching the footer period and a weekly chart" width="900">
15
+
9
16
  ## Features
10
17
 
11
18
  - **Status bar:** `๐Ÿ”ฅ 1.20M ($52.79) [today]`, turns red with `OVER BUDGET` past your limit.
@@ -41,22 +48,53 @@ pi install git:github.com/sorinirimies/pi-tokenburn
41
48
  | `/tokenburn disable` (`off`) | Turn tokenburn off: status line and panel cleared, **nothing runs in the background**. `chart` still works on demand |
42
49
  | `/tokenburn enable` (`on`) | Turn it back on. Both are remembered across sessions |
43
50
 
51
+ ### Previews
52
+
53
+ Recorded from a real pi with only this plugin loaded, on synthetic data.
54
+
55
+ **Switch what the bottom line shows** (`/tokenburn day|week|month|year|all`, or `cycle`):
56
+
57
+ ![Status line: week, month, year, all, day, then cycle](examples/vhs/generated/status.gif)
58
+
59
+ **Charts** (`/tokenburn chart day|week|month|year|all`): the current period is green, with a peak and average footer:
60
+
61
+ ![Charts: day, week, month, year and all-time](examples/vhs/generated/charts.gif)
62
+
63
+ **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:
64
+
65
+ ![Budgets: OVER BUDGET in the footer and red columns in the chart](examples/vhs/generated/budget.gif)
66
+
67
+ **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):
68
+
69
+ ![Live refresh: the counter and cost tick up as the reply lands](examples/vhs/generated/live-refresh.gif)
70
+
71
+ **Enable / disable:** off means off (nothing runs in the background), and charts still work on demand:
72
+
73
+ ![Disable clears the footer, a chart still works, enable brings it back](examples/vhs/generated/enable-disable.gif)
74
+
75
+ **Tab-completion** uses pi's own menu, with a description for every option:
76
+
77
+ ![Autocomplete for /tokenburn and its chart sub-menu](examples/vhs/generated/completion.gif)
78
+
44
79
  Tab-completion works for all of these. Unknown input prints usage instead of failing. `report <view>` is kept as an alias of `chart <view>`.
45
80
 
46
- Chart example (`/tokenburn chart day`, with a 600M day budget):
81
+ Chart example (`/tokenburn chart day`, with a 150k day budget):
47
82
 
48
83
  ```
49
- Daily tokens ยท last 14 days โ”„ budget 600.00M
50
- 1.13B โ”‚ โ–ˆโ–ˆ
51
- โ”‚ โ–ˆโ–ˆ
52
- โ”‚โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ–ˆโ–ˆโ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ–ˆโ–ˆโ”„โ–†โ–†โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„
53
- 565.16M โ”‚ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–‡โ–‡
54
- โ”‚ โ–…โ–… โ–ˆโ–ˆ โ–‚โ–‚ โ–ˆโ–ˆ โ–โ– โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–„โ–„ โ–‡โ–‡
55
- โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
56
- 26 27 28 29 30 01 02 03 04 05 06 07 08 09
57
- Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr
58
- โ–ฒ
59
- ฮฃ 3.83B ($1264.30) ยท avg 273.80M/day ยท peak 1.13B (09-29 Tue)
84
+ Daily tokens ยท last 14 days โ”„ budget 150.0k
85
+ 291.9k โ”‚ โ–ˆโ–ˆ โ–„โ–„
86
+ โ”‚ โ–ˆโ–ˆ โ–ˆโ–ˆ
87
+ โ”‚ โ–ƒโ–ƒ โ–…โ–… โ–ˆโ–ˆ โ–ˆโ–ˆ
88
+ โ”‚โ”„โ”„โ”„โ”„โ”„โ”„โ–ˆโ–ˆโ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ”„โ–ˆโ–ˆโ”„โ”„โ”„โ”„โ”„โ”„โ”„โ–†โ–†โ”„โ”„โ”„โ”„โ–ˆโ–ˆโ”„โ–ˆโ–ˆโ”„โ–…โ–…โ”„
89
+ 146.0k โ”‚ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ
90
+ โ”‚ โ–ˆโ–ˆ โ–‚โ–‚ โ–‡โ–‡ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–‡โ–‡ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ
91
+ โ”‚โ–โ– โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ
92
+ โ”‚โ–ˆโ–ˆ โ–‡โ–‡ โ–ˆโ–ˆ โ–…โ–… โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ƒโ–ƒ โ–โ– โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ
93
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
94
+ 26 27 28 29 30 01 02 03 04 05 06 07 08 09
95
+ Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr
96
+ โ–ฒ
97
+ ฮฃ 1.74M ($4.81) ยท avg 124.4k/day ยท peak 291.9k (10-07 Wed)
60
98
  ```
61
99
 
62
100
  Weeks start on Monday, in local time.
@@ -96,6 +134,17 @@ Refreshing is designed to cost nothing you can notice:
96
134
  - **Never blocks:** refreshes are fire-and-forget and errors are swallowed; the timer is unref'd and cancelled at shutdown.
97
135
  - **Off means off:** `/tokenburn disable` (or `"enabled": false`) reads no files and starts no timers.
98
136
 
137
+ ## Demo recordings
138
+
139
+ The GIFs above live in [`examples/vhs/generated/`](examples/vhs/generated) and are stored with **Git LFS** (`git lfs install` once). They are recorded with [VHS](https://github.com/charmbracelet/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:
140
+
141
+ ```sh
142
+ just vhs-all # every tape (examples/vhs/*.tape): needs vhs, ttyd, ffmpeg, pi, bun, python3
143
+ just vhs-tape charts # one tape
144
+ just vhs-list # list the tapes
145
+ just demo # try it yourself in a real pi on the same synthetic data
146
+ ```
147
+
99
148
  ## Security notes
100
149
 
101
150
  - **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**.
@@ -120,15 +169,16 @@ CI scripts are [nushell](https://www.nushell.sh) (`scripts/`), the same ones loc
120
169
 
121
170
  | Workflow | When | What |
122
171
  |---|---|---|
123
- | **CI** | push / PR | quality gate on Linux; tests on macOS, Windows and extreme time zones |
124
- | **Nightly Dependency Update** | every night (GitHub 02:00 UTC, Gitea 02:30) | `bun update` within ranges, verify on all platforms, commit `chore(deps)`; then **publish a patch** when a *runtime* dependency was upgraded or `feat`/`fix`/`perf` commits are waiting since the last tag |
125
- | **Release** | tag `vX.Y.Z` | validates the tag against `package.json`, runs the gate, `npm publish` (idempotent), creates the release |
172
+ | **CI** | push / PR | quality gate on Linux; tests on macOS and Windows, and in extreme time zones |
173
+ | **Auto-merge library updates** | CI finished on a Dependabot PR | **patch and minor** updates (GitHub Actions) are merged automatically, but only **after CI is green** on that exact commit; a **major** update waits for you. Then it starts the nightly workflow so the update ships |
174
+ | **Nightly Dependency Update** | every night (GitHub 02:00 UTC, Gitea 02:30) and after each auto-merge | `bun update` within ranges, verify on all platforms, commit `chore(deps)`; then **build, tag and publish a new patch** whenever a library was upgraded or merged, or `feat`/`fix`/`perf` commits are waiting since the last tag |
175
+ | **Release** | tag `vX.Y.Z` | validates the tag against `package.json`, runs the gate, `npm publish` (idempotent, with provenance), creates the release |
126
176
 
127
- Dev-tooling-only bumps are committed but never released on their own. A downgrade blocks the whole update.
177
+ 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.
128
178
 
129
179
  Manual release: `just bump patch` (or `minor` / `major` / `X.Y.Z`), then `just release-push`.
130
180
 
131
- **Secrets** (repo settings): `NPM_TOKEN` โ€” 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).
181
+ **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).
132
182
 
133
183
  Commits follow [Conventional Commits](https://www.conventionalcommits.org); the changelog is generated by git-cliff.
134
184
 
@@ -136,4 +186,20 @@ Commits follow [Conventional Commits](https://www.conventionalcommits.org); the
136
186
 
137
187
  Pi sessions only. For Zed, Claude Code, Codex, Gemini and more, use the Rust [tokenburn](https://github.com/sorinirimies/tokenburn).
138
188
 
189
+ ## Related plugins
190
+
191
+ Three small [pi](https://github.com/earendil-works/pi-coding-agent) extensions that save tokens without adding anything to the system prompt:
192
+
193
+ | Plugin | What it does |
194
+ |---|---|
195
+ | [**pi-edit-first**](https://github.com/sorinirimies/pi-edit-first) | Blocks whole-file `write` rewrites and hand-written project manifests, steering the agent to targeted `edit` calls and scaffolders |
196
+ | [**pi-read-guard**](https://github.com/sorinirimies/pi-read-guard) | Blocks full reads of large files, steering the agent to `offset`/`limit` or search |
197
+ | [**pi-tokenburn**](https://github.com/sorinirimies/pi-tokenburn) | Live token and cost counter in pi's footer, with charts and budgets |
198
+
199
+ ```bash
200
+ pi install npm:pi-edit-first
201
+ pi install npm:pi-read-guard
202
+ pi install npm:pi-tokenburn
203
+ ```
204
+
139
205
  MIT
package/extensions/tokenburn.ts CHANGED
@@ -953,7 +953,7 @@ export default function tokenBurnExtension(pi: ExtensionAPI) {
953
953
  rule,
954
954
  ...chart,
955
955
  rule,
956
- "/tokenburn chart <day|week|month|year|all> ยท /tokenburn <day|week|month|year|all> sets the status bar ยท cycle ยท window ยท budget ยท cache",
956
+ "chart <view> ยท <view> sets the status bar ยท cycle ยท window ยท budget ยท cache ยท live ยท on|off",
957
957
  ].join("\n"),
958
958
  "info",
959
959
  );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-tokenburn",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "Pi extension for live token usage monitoring and budget tracking (Day / Week / Month / Total). 0 prompt tokens.",
5
5
  "keywords": ["pi-package", "pi-extension", "tokenburn", "tokens", "analytics", "budget", "stats"],
6
6
  "license": "MIT",