@tmustier/pi-usage-extension

/usage - Usage Statistics Dashboard

A Pi extension that displays aggregated usage statistics across all sessions.

Compatibility

• Pi version: 0.42.4+
• Last updated: 2026-01-13

Installation

Pi package manager

pi install npm:@tmustier/pi-usage-extension

pi install git:github.com/tmustier/pi-extensions

Then filter to just this extension in ~/.pi/agent/settings.json:

{
  "packages": [
    {
      "source": "git:github.com/tmustier/pi-extensions",
      "extensions": ["usage-extension/index.ts"]
    }
  ]
}

Local clone

Add to your ~/.pi/agent/settings.json:

{
  "extensions": [
    "~/pi-extensions/usage-extension"
  ]
}

Usage

In Pi, run:

/usage

Features

Time Periods

Period	Definition
Today	From midnight (00:00) today
This Week	From Monday 00:00 of the current week
All Time	All recorded sessions

Use Tab or ←/→ to switch between periods.

Timezone

Time periods are calculated in the local timezone where Pi runs. If you want to override it, set the TZ environment variable (IANA timezone, e.g. TZ=UTC or TZ=America/New_York) before launching Pi.

Columns

Column	Description
Provider / Model	Provider name, expandable to show models
Sessions	Number of unique sessions
Msgs	Number of assistant messages
Cost	Total cost in USD (from API response)
Tokens	Total tokens (input + output)
↑In	Input tokens (dimmed)
↓Out	Output tokens (dimmed)
Cache	Cache read + write tokens (dimmed)

Navigation

Key	Action
Tab / ← →	Switch time period
↑ ↓	Select provider
Enter / Space	Expand/collapse provider to show models
q / Esc	Close

Provider Notes

Cost Tracking

Cost data comes directly from the API response (usage.cost.total). Accuracy depends on the provider reporting costs.

Cache Tokens

Cache token support varies by provider:

Provider	Cache Read	Cache Write
Anthropic	✓	✓
Google	✓	✗
OpenAI Codex	✓	✗

The "Cache" column combines both read and write tokens.

Data Source

Statistics are parsed from session files in ~/.pi/agent/sessions/. Each session is a JSONL file containing message entries with usage data. Assistant messages duplicated across branched session files are deduplicated by timestamp + total tokens (matching ccusage).

Respects the PI_CODING_AGENT_DIR environment variable if set.

Changelog

See CHANGELOG.md.