release: add usage extension

Author: emanuelcasco

README.md

@@ -21,6 +21,7 @@ This repo is a pnpm workspace monorepo. Each extension under `extensions/` can b
   - [simplify](#simplify)
   - [status-line](#status-line)
   - [team-mode](#team-mode)
+  - [usage](#usage)
 
 ## Installation
 
@@ -436,3 +437,21 @@ Full details: [extensions/team-mode/README.md](extensions/team-mode/README.md).
 ```bash
 pi install npm:pi-mono-team-mode
 ```
+
+### usage
+
+The `usage` extension adds a `/usage` command that aggregates local pi session files and renders an inline dashboard with three views:
+
+- **Summary** — totals, top providers (with horizontal bars), and an environmental footprint estimate (kWh, kg CO₂e, real-world equivalences) computed from [`impact-equivalences`](https://www.npmjs.com/package/impact-equivalences).
+- **Providers** — per-provider table that expands into per-model rows on `Enter`.
+- **Patterns** — cost-driver insights for the selected period (parallel sessions, oversized contexts, large uncached prompts, marathon sessions, top-session concentration).
+
+`Tab`/arrows cycle the period (Today / This Week / Last Week / All Time). `v` or `1`/`2`/`3` switch view. `q`/`Esc` close the panel.
+
+Full details: [extensions/usage/README.md](extensions/usage/README.md).
+
+#### Install
+
+```bash
+pi install npm:pi-mono-usage
+```

extensions/all/CHANGELOG.md

@@ -1,5 +1,13 @@
 # pi-mono-all
 
+## 1.1.0
+
+### Minor Changes
+
+### Enhanced: all
+
+- Bundle the new `pi-mono-usage` extension in the all-in-one package.
+
 ## 1.0.1
 
 ### Patch Changes

extensions/all/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mono-all",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "All pi-mono extensions and bundled skills",
   "type": "module",
   "keywords": [
@@ -24,7 +24,8 @@
     "pi-mono-sentinel": "workspace:*",
     "pi-mono-simplify": "workspace:*",
     "pi-mono-status-line": "workspace:*",
-    "pi-mono-team-mode": "workspace:*"
+    "pi-mono-team-mode": "workspace:*",
+    "pi-mono-usage": "workspace:*"
   },
   "bundledDependencies": [
     "pi-mono-ask-user-question",
@@ -42,7 +43,8 @@
     "pi-mono-sentinel",
     "pi-mono-simplify",
     "pi-mono-status-line",
-    "pi-mono-team-mode"
+    "pi-mono-team-mode",
+    "pi-mono-usage"
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -66,7 +68,8 @@
       "./node_modules/pi-mono-sentinel/index.ts",
       "./node_modules/pi-mono-simplify/index.ts",
       "./node_modules/pi-mono-status-line/index.ts",
-      "./node_modules/pi-mono-team-mode/index.ts"
+      "./node_modules/pi-mono-team-mode/index.ts",
+      "./node_modules/pi-mono-usage/index.ts"
     ],
     "skills": [
       "./node_modules/pi-mono-figma/skills",

extensions/usage/CHANGELOG.md

@@ -0,0 +1,11 @@
+# pi-mono-usage
+
+## 0.1.0
+
+### Initial release
+
+- `/usage` command renders an inline dashboard over local pi session files.
+- Three views: Summary (with sustainability impact), Providers (table with model expansion), Patterns (cost-driver insights).
+- Period selector for Today / This Week / Last Week / All Time.
+- Sustainability impact powered by `impact-equivalences` (electricity, carbon, real-world equivalences).
+- Tabular layout adapts to terminal width (full → compact → minimal).

extensions/usage/README.md

@@ -0,0 +1,38 @@
+# usage extension
+
+Adds a `/usage` slash command that reads your local pi session files, aggregates token spend, and renders an inline dashboard with three views.
+
+## Install
+
+```bash
+pi install npm:pi-mono-usage
+```
+
+## Views
+
+- **Summary** — totals, top providers, and an environmental footprint estimate (kWh, kg CO₂e, real-world equivalences) computed from [`impact-equivalences`](https://www.npmjs.com/package/impact-equivalences).
+- **Providers** — per-provider table that expands into per-model rows. Includes session/call counts, cost, and token breakdown (input, output, cache).
+- **Patterns** — cost-driver insights for the selected period: parallel sessions, oversized contexts, large uncached prompts, marathon sessions, and top-session concentration.
+
+## Period selector
+
+Tab between `Today`, `This Week`, `Last Week`, and `All Time`. Each period is computed once on open from the same parsed dataset, so cycling is instant.
+
+## Keybindings
+
+| Key               | Action                                 |
+| ----------------- | -------------------------------------- |
+| `Tab` / `←` / `→` | Cycle period                           |
+| `v`               | Cycle view                             |
+| `1` / `2` / `3`   | Jump to Summary / Providers / Patterns |
+| `↑` / `↓`         | Move provider cursor (Providers view)  |
+| `Enter` / `Space` | Expand / collapse a provider           |
+| `q` / `Esc`       | Close the panel                        |
+
+## Data source
+
+Reads `~/.pi/agent/sessions/**/*.jsonl` (or `$PI_CODING_AGENT_DIR/sessions`). For each `assistant` message with a `usage` block, the extension records cost and token counts. Duplicate turns from branched session files are deduplicated by a fingerprint over timestamp + token counts.
+
+## Sustainability estimate
+
+The Summary view feeds the period's charged tokens (`input + output + cacheWrite`) into `impact-equivalences` `estimateAiImpact`, which returns electricity (kWh) and carbon (kg CO₂e) ranges along with formatted real-world equivalences (e.g. _"~X average US households for a day"_). Estimates are illustrative — see the package's source attribution for boundaries and assumptions.