/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.