usage

A Claude Code–style /usage panel for pi.

Shows how your spend and tokens are distributed across models, skills, plugins, tools, and projects, bucketed by time window — with always-visible 5-hour and weekly quota bars. Mirrors the layout and wording of Claude Code's /usage screen.

---

🚀 Install

⚠️ Use pi install — NOT npm install. Plain npm install only drops files in node_modules. Pi does not scan that folder, so the package is never detected and /usage won't appear. You must register it with pi install so it lands in "packages" in ~/.pi/agent/settings.json.

pi install npm:@zaganjade/pi-usage

Then inside pi:

/reload

Verify it loaded:

pi list          # should show npm:@zaganjade/pi-usage

Type / — /usage should appear in slash autocomplete.

Don't do this (common mistake — package installs but pi ignores it):

npm install -g @zaganjade/pi-usage   # ❌ pi will not detect this

---

Overview (/usage)

Seven views via Tab or 1–7. The navigation bar is a two-row menu: colored icon tabs on top, plus Pi-chan (the panel mascot) with a contextual hint for the active view. Overview shows quota bars, headline stats, active provider, top consumer, a trend sparkline, and compact top models.

────────────────────────────────────────────────────────────────
 Usage ────────────────────────────────  5H │ DAY │ WEEK │ ALL

╭─ views  ◈1 Overview │ ◎2 Models │ … │ ✦7 Wrapped  ─────────╮
  (◕‿◕)  Pi-chan  Quota bars & headline stats…    Tab · 1-7 jump

  Showing: last 24 hours              last activity 2m ago  ·  254 sessions

  5-hour quota     ████░░░░░░░░░░░░  12% used / 145.9M · 88% left · resets 4h 58m
  Weekly quota     ██████░░░░░░░░░░  55% used / 176.7M · 45% left · resets 11h 49m
  live from provider

  ↑51.8M  ↓3.7M  ⚡97.7M  145.9M tokens   ·  855 turns

  Top consumer
  73% of usage came from model glm-5.2

  Trend  ▁▂▃▅▆▅▄▃▂▁▂▃  Jun 10 → Jun 17

  Top models                        %   tokens
  glm-5.2                        73% ███████████████ 106.5M

  → Tab or 1-7 to explore · ✦7 opens Wrapped AI

Models view (/usage-models)

Full attribution breakdown — model table with tok/s, Skills, Bundles (@debug, …), Plugin usage (with contributing skills/tools), Tools (per-tool glyphs and share bars), and Projects.

  Models                            %   tokens   tok/s
  glm-5.2                        73% ███████████████ 106.5M   142/s
  tok/s · est. avg output speed

  Skills                            %   tokens
  systematic-debugging             18% ███░░░░░░░░░░░░  25.4M

  Bundles                           %   tokens
  @debug                           22% ████░░░░░░░░░░░  31.1M

  Plugin usage                      %   tokens  via
  frontend-design                12% ██░░░░░░ 720k   frontend-design
  (core / no plugin)             59% ██████░░ 3.6M   builtin tools only

  ⚙ Pi-chan tracked these tool calls
  Tools                             %   tokens
  ↳ read                         34% ██████░░░░░░░░░  48.2M
  $ bash                         22% ████░░░░░░░░░░░  31.1M
  ✎ write                        18% ███░░░░░░░░░░░░  25.4M
  glyph · tool type hint

Wrapped AI (/usage-wrapped)

Year-in-review report with a professional layout and Pi-chan as a sidebar accent. Pose and footer caption react to your stats (streak, peak hour, top model). Cycle years with [ / ] or y.

  Wrapped  2025  ◂ [ ] ▸  ·  y ─────────────────────────────

  ∧＿∧ │  145.9M tokens  tokens
 (◕‿◕)│  855 turns  ·  89 active days  ·  4 models  ·  2 providers
 /つ ✦│  Favorite model    glm-5.2       Top provider    zai
  ～～ │  Longest streak     12 days      Peak hour       11 PM

  Highlights ────────────────────────────────────────────────
  Models used    4              Providers    2
  Projects       8              Top project  my-app

  Monthly activity ──────────────────────────────────────────
  tokens by month
      ▄▄▄     ▄▄▄
      ███ ░░░ ███ ░░░ …
  Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
  Less ·▪▩▣█ More
  Peak month  Mar  48.2M  ·  6 active months

  Rankings ──────────────────────────────────────────────────
  Models
  glm-5.2                        73% ███████████████ 106.5M
  Providers
  zai                            81% ██████████████░ 118.2M

 (≧◡≦) │  Pi-chan  73% of usage on glm-5.2.

Views

The panel is organized into seven menu views (Tokscale-inspired, extended with Wrapped AI), switchable inside /usage and openable directly via shortcuts:

View	Shows
Overview	Quota bars, headline stats, active-provider quota, top consumer, a 30-day trend sparkline, and the top models.
Models	Detailed model table with tok/s, plus Skills, Bundles (@name from pi-multi-skill), Plugin usage, Tools (glyph + share bar), and Projects breakdowns.
Daily	Per-day rows with an activity bar plus exact cost, tokens, uptime (active span), and the day's top model; topped with all-time totals (uptime / tokens / cost). Sortable by date or usage.
Stats	GitHub-style contribution graph with month labels, an interactive time-range selector (all / 7d / 30d via a/w/m), and a two-column summary (total, turns, active days, favorite model, current/longest streak, busiest day, peak hour, averages) plus a fun usage comparison.
Hourly	Time-of-day breakdown (0–23h, all days combined): activity bars, tokens, turns, and top model per hour — spot your peak coding windows.
Agents	Usage by provider/backend (e.g. zai, openai-codex, 9Router): share bars, tokens, project count, and top model per provider. Sortable by usage or name.
Wrapped AI	Year-in-review report: headline totals, Highlights grid, Stats-style monthly heatmap, model/provider rankings with share bars, and a Pi-chan footer insight. Sidebar mascot pose reacts to streaks and peak hours. Cycle years with [ / ] or y.

UI — Pi-chan & navigation

The panel uses a lightweight TUI mascot, Pi-chan, to make navigation feel friendlier without sacrificing readability:

Element	Behavior
View tabs	Each of the seven views has an icon (◈ Overview, ◎ Models, ✦ Wrapped, …) and a distinct accent color when selected.
Hint row	Pi-chan's face plus a one-line description of the active view (e.g. "Year in review — [ ] or y to change year" on Wrapped).
Wrapped sidebar	On wide terminals, Pi-chan sits beside the hero stats with a vertical rule; pose changes for celebrate / night-owl / curious / empty-year moods.
Tools glyphs	Common tool names show a type hint prefix (↳ read, $ bash, ✎ write, ⌕ grep, …) with per-row share bars.
Wrapped sections	Hairline section headers (Highlights, Monthly activity, Rankings) match the Stats/Daily report rhythm.
Monthly activity	Stats-style vertical heatmap (12 month columns, graded █ blocks, Less → More legend, peak-month callout). Narrow terminals fall back to horizontal share bars.

Pi-chan copy is informational, not decorative — footer captions summarize your standout stat in plain language.

Commands

Command	Description
/usage	Open the interactive usage panel (Overview view).
/usage-models	Open the panel directly on the Models view.
/usage-daily	Open the panel directly on the Daily summary view.
/usage-stats	Open the panel directly on the Stats (contribution graph) view.
/usage-hourly	Open the panel directly on the Hourly (time-of-day) view.
/usage-agents	Open the panel directly on the Agents (provider) view.
/usage-wrapped	Open the panel directly on the Wrapped AI year-in-review view.
/usage-config	Set your 5-hour and weekly USD budgets.
/usage-pricing	Set a manual per-model price ($/M tokens) so cost shows for token-priced / proxied models pi records as $0.
/usage-widget	Toggle a compact always-on spend widget above the editor.

Keys inside /usage

Key	Action
Tab / Shift+Tab, ← / →	Switch view (Overview ↔ … ↔ Wrapped AI)
1 2 3 4 5 6 7	Jump to Overview / Models / Daily / Stats / Hourly / Agents / Wrapped
5 / d / w / a	On Overview & Models: switch window (5 hours / day / week / all). On other views, 5 opens Hourly.
a / w / m	Stats range: all time / last 7 days / last 30 days (Stats view)
c / t / n	Models or Agents view: sort by usage (c/t) or name (n)
t / c / d	Daily view: sort by tokens / cost / date — press the same key again to flip ascending ↔ descending
[ / ] / y	Wrapped AI: previous / next calendar year
j k / ↑ ↓	Scroll • space/ctrl+d half-page down, ctrl+u/b up
g / G	Jump to top / bottom
r	Force re-scan of sessions
s	Set budgets (same as /usage-config)
q / esc	Close

Configuration

~/.pi/agent/usage.json (auto-created on first change):

{
  "fiveHourLimit": 20,
  "weeklyLimit": 100,
  "fiveHourTokenLimit": 2000000,
  "weeklyTokenLimit": 10000000,
  "showWidget": false,
  "excludeProjects": ["/tmp/throwaway"],
  "maxSessions": 1000,
  "modelPrices": {
    "claude-opus-4.7": { "input": 15, "output": 75, "cacheRead": 1.5, "cacheWrite": 18.75 },
    "glm-5-turbo": { "input": 0.6, "output": 2.2 }
  }
}

• fiveHourLimit / weeklyLimit — USD budgets for priced providers (e.g. Anthropic, OpenAI metered). 0/omitted shows raw spend with no bar.
• fiveHourTokenLimit / weeklyTokenLimit — token budgets for token-priced providers (e.g. zai/GLM, where per-token cost is unknown). 0/omitted shows raw token usage with no bar.
• showWidget — keep a one-line spend summary above the editor.
• excludeProjects — cwd prefixes to skip during aggregation.
• maxSessions — safety cap on how many session files to scan.
• modelPrices — prices in USD per 1M tokens used to compute cost for token-priced / proxied models that pi records with $0 (e.g. zai/GLM, 9Router kr/…, cx/…). The extension ships with default prices for common models (src/prices.ts, taken from official provider pricing pages); your modelPrices entries override those per key. A cost recorded by pi always wins; the price table only fills gaps. Keys match the model ID exactly, or by base name (after the last /) so claude-opus-4.7 covers kr/claude-opus-4.7 and cx/claude-opus-4.7. Set entries interactively with /usage-pricing. Prices are estimates — verify against your provider.

Adaptive units

The quota bars, headline stats, and breakdown sections automatically switch unit based on the active provider:

• USD when the selected window has meaningful $ cost (priced providers).
• Tokens when the window's cost is 0 (token-priced providers like zai/GLM, where the model has no pricing in pi's registry). For these, tokens are the real usage signal — the panel shows e.g. 1.3M / 2M (63%) against your fiveHourTokenLimit, and the live per-minute rate-limit headers below give the real-time "remaining this window" from the provider.

Performance

The first scan parses every session file once (can take a few seconds for large histories). Results are then cached per session file to ~/.pi/agent/usage-cache.json, keyed by each file's mtime + size. Subsequent opens — even after restarting pi — only re-parse sessions that actually changed, so the panel comes up in well under a second instead of re-reading everything. The cache is rebuilt automatically if you change modelPrices (costs are baked in at parse time) or when the cache schema version bumps (currently v4, which adds multi-skill skills[] and bundles[] on each turn). Legacy entries are normalized on load. Delete ~/.pi/agent/usage-cache.json to force a full re-scan.

How it works

Pi records per-turn usage (tokens + cost) on every assistant message across all session files in ~/.pi/agent/sessions/. This extension opens each file once, walks the entries, and attributes every assistant turn to:

• model — from message.model
• project — from the session's working directory
• skill — detected via parseSkillBlocks() on the preceding user message (multi-skill aware — every <skill name="…"> in a /skills activation is counted separately)
• bundle — detected via bundles="…" on <manually_attached_skills> (e.g. @bmad-planning, @debug)
• plugins / tools — from the tool calls in the assistant message, mapped to their owning package via pi.getAllTools() / pi.getCommands()

When using pi-multi-skill, a single /skills @debug,frontend-design turn attributes usage to both systematic-debugging and frontend-design in the Skills section, and @debug in the Bundles section when a preset bundle was used.

Like Claude Code, these are independent characteristics of your usage, not a disjoint partition — a single turn can contribute to several buckets, so percentages need not sum to 100% across categories.

Active provider quota

Beyond your own session history, the panel also surfaces the active provider's view of your quota. It detects the active provider from ctx.model and shows:

• OpenAI Codex (subscription, e.g. ChatGPT Plus/Pro via Codex CLI) — the 5-hour and weekly rate-limit windows come from the live response headers (x-codex-primary-used-percent, x-codex-secondary-used-percent, x-codex-primary-reset-at, x-codex-secondary-reset-at) that pi captures on every Codex request. No extra auth needed — the headers are always fresh, straight from pi's own authenticated Codex call. Also shows the plan/limit name (x-codex-limit-name) and purchased credits balance (x-codex-credits-*) when present. The /backend-api/wham/usage REST endpoint is not used because its OAuth token in ~/.codex/auth.json is frequently stale/rotated (single-use refresh tokens).
• ZAI (GLM coding plans) — the authoritative 5-hour and weekly quota is fetched live from ZAI's subscription API (https://api.z.ai/api/monitor/usage/quota/limit, undocumented but used by the ZAI management UI). It reports the upstream used/remaining percentage with a live reset countdown — no budget config needed, these ARE the plan's 5h/weekly limits straight from the source. Also shows web-search quota when present. (Two endpoints are tried: api.z.ai intl + open.bigmodel.cn CN.)
• OpenRouter — account credits remaining (/api/v1/credits).
• OpenAI — 5h/7d spend via /v1/organization/costs (+ monthly hard limit when readable).
• Other / fallback — when a provider has no upstream quota API, the bars fall back to session-derived usage (USD or tokens) against an optional user budget via /usage-config.
• Rate-limit windows — captured universally from every provider HTTP response (Anthropic, OpenAI, OpenRouter, Google, …) via the after_provider_response event, with live reset countdowns.

API keys are resolved with pi's own resolver (getEnvApiKey(provider) from @earendil-works/pi-ai, which mirrors pi's env-var precedence). Providers that use OAuth (Anthropic subscription, GitHub Copilot) won't resolve here — their rate-limit headers still work and are shown.

Why budgets are user-defined: pi works with any provider, so it has no built-in quota (unlike Claude Code's subscription). Set limits that match your plan and the panel tracks progress against them.

Files

File	Purpose
index.ts	Entry point — registers commands (incl. /usage-models, /usage-daily, /usage-stats), orchestrates scan + widget
view.ts	The interactive TUI panel (UsageView) — Pi-chan menu, Overview / Models / … / Wrapped AI views
mascot.ts	Pi-chan ASCII art, view tab icons, tool glyphs, Wrapped captions
aggregate.ts	Session scanning + windowing + attribution; multi-skill skills[]; legacy turn normalization
provider.ts	Active-provider detection + rate-limit parsing + live quota fetch
config.ts	Load/save ~/.pi/agent/usage.json (merges bundled default prices)
cache.ts	Persistent incremental scan cache (~/.pi/agent/usage-cache.json)
prices.ts	Bundled default model prices ($/M tokens) from official provider pricing pages
format.ts	Token/currency/bar/label formatting helpers

Install

Use pi install, not plain npm install. Pi registers packages in settings.json under "packages" and loads extensions from the pi.extensions manifest in package.json.

pi install npm:@zaganjade/pi-usage

Then run /reload in pi (or restart the CLI). Commands like /usage should appear in slash autocomplete.

Quick test without persisting to settings:

pi -e npm:@zaganjade/pi-usage

From GitHub (monorepo):

pi install git:github.com/ZaganJade/pi-extension

From a local path:

pi install ./usage

Troubleshooting

Symptom	Fix
/usage not in autocomplete	Run pi install npm:@zaganjade/pi-usage, then /reload
Installed with npm install -g but pi ignores it	Use pi install npm:@zaganjade/pi-usage instead
Added npm:... to "extensions" in settings	Wrong key — use "packages", or run pi install
Extension listed but disabled	Run pi config and enable the extension resource

Verify install:

pi list
# should show: npm:@zaganjade/pi-usage

Note: npm install only downloads the package to disk. Pi does not auto-scan global or local node_modules — you must register the package with pi install so it appears in "packages".

No build step; pi loads TypeScript directly via jiti.

Changelog

v1.9.0

• Pi-chan navigation — two-row menu with icon tabs and per-view hints
• Wrapped AI — report layout (Highlights / Monthly activity / Rankings), sidebar mascot, footer caption
• Monthly activity — vertical heatmap aligned with Stats view (Less → More legend, peak-month callout)
• Tools section — per-tool glyphs and colored share bars
• Bundle attribution — Bundles breakdown for @bundle activations from pi-multi-skill
• Multi-skill skills[] — every skill in a chain attributed separately
• Cache v4 — skills[], bundles[], tools[] on each turn; legacy entries normalized on load

v1.8.0

• Seven views including Wrapped AI, Agents, Hourly; live ZAI/Codex quota; incremental scan cache