# usage

Local usage statistics dashboard for Pi.

## Install / load

Loaded through the root pi-ext package.
See [../../README.md](../../README.md).

## Commands / tools / settings

- Command:
  `/usage` — show usage statistics dashboard.
- Tools:
  none.
- Hooks:
  none.
- Settings:
  none.

## Behavior

- Reads local Pi session JSONL files across all projects by scanning the parent
  of the current session dir.
- Parses assistant messages with `usage`, `provider`, and `model` fields.
- Aggregates sessions, messages, cost, tokens, input, output, and cache by
  provider and model.
- Renders the `klaus` provider as `anthropic (klaus)` because it carries the
  Claude subscription traffic.
- Period tabs:
  Today, This Week, Last Week, All Time.
- Table keys:
  `Tab`/`←`/`→` switch period, `↑`/`↓` select provider, `Enter`/`Space` expand
  models, `v` toggles insights, `q`/`Esc` closes.
- Insights view shows cost-weighted hints for parallel sessions, large context,
  uncached prompts, long sessions, and top-session concentration.
- No UI context:
  command returns without rendering.

## Debug

Opt-in metadata diagnostics: [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `command.handle.start`, `command.handle.finish`, `command.handle.error`.