pi-usage-panel

A pi extension that registers the /usage command: an aggregated panel combining real Kimi quota (from the Kimi API) with local pi session consumption (scanned from your own session logs).

Features

• /usage — aggregated report with two sections:
  • KIMI — live quota (plan, usage windows, booster wallet, parallelism) fetched from GET https://api.kimi.com/coding/v1/usages.
  • PI-CODE — local token/cost consumption aggregated from your pi session files (~/.pi/agent/sessions), grouped by today / week / month / total and by provider/model.
• /usage --json — raw aggregated JSON output (API key never included; deep redaction applied as defense in depth).
• /usage --refresh — bypasses the in-memory cache.
• TUI panel — in interactive (TUI) mode, results are shown in a compact scrollable panel with a caramel-colored frame (↑/↓/PgUp/PgDn to scroll, Esc/q to close). In RPC/print mode the same content is rendered as plain text. Usage windows are shown in the largest unit (e.g. Janela 5h), and identical aggregation periods (e.g. week = month = total) are deduplicated.

Note: the panel's output labels are currently in Portuguese (pt-BR). Internationalization is on the roadmap — contributions welcome.

Installation

From GitHub:

pi install git:github.com/ProCleiton/pi-usage-panel

From npm:

pi install npm:pi-usage-panel

Requires Node.js >= 22 (the extension and its tests rely on native TypeScript type-stripping).

Configuration

Configuration is done exclusively through environment variables. There is no fallback to credential files of any kind.

Variable	Default	Description
KIMI_CODE_API	—	Kimi API key. Required for the KIMI section; without it, that section shows an "unavailable" notice.
PI_USAGE_CACHE_TTL_MS	60000	In-memory cache TTL in milliseconds (lazy; no timers).
PI_SESSIONS_DIR	~/.pi/agent/sessions	Root directory of pi session files (scanned recursively for *.jsonl).
PI_USAGE_TIMEZONE	America/Fortaleza	IANA timezone used for period boundaries (today/week/month) and displayed dates.

The API key is never printed, logged, or included in errors/--json output — every error message and the JSON payload pass through a sanitizer that redacts any accidental occurrence of the key.

Data sources & privacy

This extension reads from exactly two sources:

1. Kimi API — a single authenticated GET to https://api.kimi.com/coding/v1/usages, using the key from KIMI_CODE_API. This is the only network call and the only third party that ever receives anything (your API key, as a Bearer token, to Kimi itself).
2. Local session files — a read-only, streaming scan of $PI_SESSIONS_DIR/**/*.jsonl (default ~/.pi/agent/sessions). Only lines with assistant usage records are parsed; malformed lines and unreadable files are skipped.

• No data is sent anywhere besides the Kimi API call described above. There is no telemetry, no analytics, no remote logging.
• No credentials are stored in the code, and no credential files are ever read — the key comes only from the environment variable.
• Session scanning is local and read-only; nothing is written back.

Development

Run the test suite (pure Node, no dependencies):

node test/run-tests.mjs

Screenshots

• TODO: TUI panel screenshot
• TODO: --json output sample
• TODO: print-mode output sample

License

MIT — see LICENSE. Copyright (c) 2026 ProCleiton.