pi-usage-report

English | 简体中文

A pi extension that reports token usage and estimated cost for any time range — today, this week, this month, a rolling window, or an arbitrary date range — and prints the money in your local currency.

Zero configuration, zero dependencies. It reads the transcripts pi already writes.

/usage
[usage] today  2026-10-24 00:00 → 2026-10-24 02:39
  requests 384   sessions 6   22 transcript file(s)
  input 318,325   cache read 47,127,680   cache write 0
  output 299,840   (reasoning 156,413)
  total 47,745,845 tokens   cache hit 99.3%
  cost  $1.0043  ≈  ¥6.72  (USD/CNY 6.688225, 0m old, live)

  by model
    deepseek-flash         384 req    54.49M tok    $0.8001  ¥5.35

  by day
    2026-10-24    54.49M tok     ¥5.35  ████████████  384 req

Features

• Any range: today, yesterday, week, lastweek, month, lastmonth, all, rolling windows (12h, 7d, 2w, 3m, 10天) and explicit local dates (2026-09-01..2026-09-30). Chinese aliases work too (今天, 昨天, 本周, 上月, 全部 ...).
• Cost in local currency: pi records per-request cost in USD from the model catalog; the extension multiplies by a USD→local rate and prints both. The rate is fetched live (cached 12 h) or pinned.
• Breakdowns: per model, per day (with bars), and — in the expanded view — top sessions.
• Machine-wide: aggregates every project's sessions, not just the current one.
• Durable, quiet output: the report is stored as a display-only session entry, so it stays in the transcript, can be re-read later, and is never sent to the model (no tokens burned to look at it).
• Zero dependencies, zero config: no network, no daemon, nothing to install besides the package.

Install

Requires Node.js ≥ 20 (bundled with pi).

1. From npm (recommended)

pi install npm:pi-usage-report

2. From Gitee

pi install git:gitee.com/zxh126/pi-usage-report

3. Manually into the user extensions directory

git clone https://gitee.com/zxh126/pi-usage-report "$HOME/.pi/agent/extensions/pi-usage-report"

(No npm install needed — the extension has no dependencies.) Windows path: %USERPROFILE%\.pi\agent\extensions\pi-usage-report.

4. Try it once

pi -e npm:pi-usage-report
pi -e ./pi-usage-report

Uninstall

pi remove npm:pi-usage-report

Commands

/cost is an alias for /usage.

Expand the entry in the transcript (default key: Ctrl+E) to see top sessions, the report timestamp and the config hint.

How the cost is estimated

1. For every assistant message pi records usage.input / output / cacheRead / cacheWrite / reasoning / totalTokens and a cost object in USD, computed from models.json pricing. The extension just sums those — it never invents a price.

2. Local amount = USD × rate, where the rate is the published one: https://open.er-api.com/v6/latest/USD → rates[<currency>] = units of your currency per 1 USD (e.g. 6.688225 for CNY), no API key and no hand-maintained table. Lookup order:

   #	Source	Shown as
   1	usdRate in the config — an explicit pin	fixed
   2	cached fetch younger than 12 h	cache, <n>m old
   3	a fetch made just now	live, <n>m old
   4	cached fetch older than 12 h and the fetch failed	stale, <n>m old
   5	nothing usable	— plus a hint to pin one

   A rate is never invented: with no pin, no cache and no network, the report prints the USD figure and — instead of a made-up exchange rate. PI_OFFLINE=1 disables the fetch, so cases 1 / 2 / 4 / 5 apply.

3. Requests that consumed tokens but carry no pricing (a model without a cost table) are counted and reported as a warning, so the number is never silently low.

Config file (<agent-dir>/pi-usage-report.json, everything optional):

{
  "currency": "CNY",
  "symbol": "¥",
  "usdRate": 6.6882,
  "rateMode": "fixed"
}

• currency / symbol — default CNY / a symbol table lookup.
• usdRate — optional pin. Its presence alone is enough to pin the rate (no rateMode needed).
• rateMode — "fixed" (pin) or "auto" (ignore the pin and use the published rate).

/usage rate <value> writes usdRate + rateMode: "fixed"; /usage rate auto deletes the pin and refetches immediately.

How it works

<agent-dir>/sessions/**/*.jsonl      (pi's own transcripts)
        │  read-only, one pass
        ▼
assistant messages with `usage`      → buckets by model / day / session
        │
        ▼
report entry (appendEntry)           → rendered in the TUI, never sent to the model

• The data source is literally the session files pi persists, so the numbers match what pi itself shows; no network call is involved in counting.
• --session-dir (flat directory) and the default per-project layout are both handled.
• Nothing is written except the report entry and, when you use /usage rate, the config/cache files.

Known limitations

• Only what is on disk: deleted or rotated session transcripts are not counted, and a fork/clone counts its own copy of the history it inherited.
• Cost is only as good as the pricing in your models.json; models without pricing show up as "no pricing data" instead of a guessed number.
• The rate is the daily reference rate published by the API above, not your provider's billing rate; treat the money column as an estimate (±a few %).
• Session transcripts are read on demand: on a machine with thousands of sessions the first /usage all takes a moment (a report over ~500 MB of transcripts is still sub-second here).

Development

pi-usage-report/
├── index.ts          # the extension (single source file, no dependencies)
├── package.json      # pi manifest: pi.extensions -> ./index.ts
├── LICENSE           # MIT
├── README.md         # this file
└── README.zh-CN.md   # Chinese translation

• Runs inside pi through its jiti loader — no build step, no dependencies.
• The renderer returns a plain object with render(width), so the extension does not even import the TUI package.
• Manual check without installing: pi -e <repo path> then /usage in the TUI, or drive it over RPC (pi --mode rpc → {"type":"prompt","message":"/usage month"}).

Release flow (maintainer): bump version → commit → push to Gitee → npm publish --registry=https://registry.npmjs.org.

License

MIT © 2026 zxh126