pi-usage

Pi package that reports token usage and cost from session usage metadata.

Behavior

Run /usage to report token and cost totals for the current session branch. Run /usage --all to scan persisted session JSONL files from the default session roots:

• $PI_SESSION_DIR
• $PI_CODING_AGENT_DIR/sessions
• ~/.pi/agent/sessions
• ~/.pi/sessions

The report is grouped by provider and model, and includes turns, input tokens, output tokens, cache read/write tokens, total tokens, and cost.

Pi stores provider-reported usage on assistant messages in session JSONL files. This extension reads those message.usage fields, so /usage --all backfills from historical JSONL files even for sessions where the extension was not installed.

Lifetime scans cache per-file summaries in ~/.pi/usage-cache.json. Later /usage --all runs still discover session files, but only re-read JSONL files whose size or modification time changed. An all-session scan also records session project paths, so /usage --project can reuse warmed /usage --all cache entries. Set $PI_USAGE_CACHE_FILE to override the cache location.

Run /usage --project to scan persisted sessions from the default roots but include only session files whose session metadata points at the current project directory. This also works with --path to filter a specific session directory or file.

If old session entries do not contain usage metadata, they are skipped because exact usage cannot be reconstructed from transcript text alone.

Commands

/usage
/usage --all
/usage --backfill
/usage --project
/usage --json
/usage --all --json
/usage --project --path /path/to/session-or-directory
/usage --path /path/to/session-or-directory

Install

pi install npm:@foxfirecodes/pi-usage

Development

From this checkout:

pi install .

Or try it for one run:

pi -e /path/to/pi-extensions/packages/pi-usage

To run automated tests:

pnpm test