Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/usage/README.md

Raw
Rendered preview
usage

usage

Past Pi sessions contain useful signals about where tokens and cost went, but they are scattered across session files. usage opens a local dashboard that summarizes usage by provider and model over useful time ranges.

usage demo: synthetic local session records summarized and expanded by provider

Use

Run /usage in Pi. Choose Today, This Week, Last Week, or All Time with Tab or the arrow keys. Use ↑ and ↓ to select a provider, then Enter or Space to expand its models. Press v for usage insights. Press q or Esc to close the dashboard.

The demo uses one synthetic response record; it does not read or display your session history.

The dashboard reads the same session stores as pi --resume, across projects and child sessions, and does not render outside a UI session. It includes assistant responses, standalone usage, tool results, compaction, and branch-summary usage. Costs use recorded values; unlike the cost footer, the dashboard does not estimate missing prices from the model catalog. ≈ marks any provider, model, or period total unless every contributing record reports a provider-billed total, including zero. Historical records without that flag count as estimated. Totals include cached tokens; time ranges use response timestamps with entry timestamps as fallback. Standalone usage retains its recorded provider and model. Tool, compaction, and branch-summary usage lack a provider in Pi's native schema, so the dashboard groups them under unattributed native rather than assigning them to a provider. Copied fork records are counted once when their persisted identity and usage match; separate responses and legacy records without usable identity remain distinct. Each session file counts its own records once, so tools must not also report work persisted in a child session. Sessions recorded by tools that did so, such as older PiPi versions, count that child work twice. Pi's native Usage schema requires a numeric monetary total, so media without native usage or a known amount remains uncovered rather than displayed as free. Use it only where aggregating those local session records is appropriate for you.

Installation

Reference

Commands

Command Purpose
/usage Show usage statistics dashboard
<img src="assets/banner.svg" alt="usage" height="70">

# usage

Past Pi sessions contain useful signals about where tokens and cost went, but they are scattered across session files.
usage opens a local dashboard that summarizes usage by provider and model over useful time ranges.

![usage demo: synthetic local session records summarized and expanded by provider](assets/demo.gif)

## Use

Run `/usage` in Pi.
Choose Today, This Week, Last Week, or All Time with `Tab` or the arrow keys.
Use `↑` and `↓` to select a provider, then `Enter` or `Space` to expand its models.
Press `v` for usage insights.
Press `q` or `Esc` to close the dashboard.

The demo uses one synthetic response record; it does not read or display your session history.

The dashboard reads the same session stores as `pi --resume`, across projects and child sessions, and does not render outside a UI session.
It includes assistant responses, standalone usage, tool results, compaction, and branch-summary usage.
Costs use recorded values; unlike the cost footer, the dashboard does not estimate missing prices from the model catalog.
`≈` marks any provider, model, or period total unless every contributing record reports a provider-billed total, including zero.
Historical records without that flag count as estimated.
Totals include cached tokens; time ranges use response timestamps with entry timestamps as fallback.
Standalone usage retains its recorded provider and model.
Tool, compaction, and branch-summary usage lack a provider in Pi's native schema, so the dashboard groups them under `unattributed native` rather than assigning them to a provider.
Copied fork records are counted once when their persisted identity and usage match; separate responses and legacy records without usable identity remain distinct.
Each session file counts its own records once, so tools must not also report work persisted in a child session.
Sessions recorded by tools that did so, such as older PiPi versions, count that child work twice.
Pi's native `Usage` schema requires a numeric monetary total, so media without native usage or a known amount remains uncovered rather than displayed as free.
Use it only where aggregating those local session records is appropriate for you.

[Installation](../../README.md#install)

## Reference

<!-- config:start -->
### Commands

| Command | Purpose |
| --- | --- |
| `/usage` | Show usage statistics dashboard |
<!-- config:end -->