@hank-warren/pi-stats 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +33 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,6 +8,12 @@ A compact, theme-aware `/stats` dashboard for [Pi](https://pi.dev). It totals th
|
|
|
8
8
|
pi install npm:@hank-warren/pi-stats
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
+
Try it for a single run without installing:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pi -e npm:@hank-warren/pi-stats
|
|
15
|
+
```
|
|
16
|
+
|
|
11
17
|
Do not install this standalone package on a host that also installs the aggregate `hank-warren/pi-extensions` Git package; that would load the extension twice.
|
|
12
18
|
|
|
13
19
|
## Use
|
|
@@ -45,6 +51,33 @@ Records are de-duplicated by `id`, counted in every total, and shown as their ow
|
|
|
45
51
|
|
|
46
52
|
The standard Pi session root, the current external session directory, `PI_CODING_AGENT_SESSION_DIR`, and a configured `subagents.defaultSessionDir` are discovered automatically. Add unusual one-off roots with the platform-delimited `PI_STATS_SESSION_DIRS` environment variable.
|
|
47
53
|
|
|
54
|
+
## Configuration
|
|
55
|
+
|
|
56
|
+
There is no config file; behavior is controlled entirely by environment variables.
|
|
57
|
+
|
|
58
|
+
| Env var | Default | Purpose |
|
|
59
|
+
| --- | --- | --- |
|
|
60
|
+
| `PI_STATS_DISABLE_USAGE_SIDECARS` | unset | Set to `1` to ignore all extension usage sidecars and count only session transcripts. |
|
|
61
|
+
| `PI_STATS_SESSION_DIRS` | unset | Extra session roots to scan, joined by the platform path delimiter (`:` on Unix, `;` on Windows). Added to the automatically discovered roots. |
|
|
62
|
+
| `PI_CODING_AGENT_SESSION_DIR` | unset | Standard Pi variable; the directory it names is picked up as a session root. |
|
|
63
|
+
| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | Standard Pi variable; determines where the cache and sidecars are read from. |
|
|
64
|
+
|
|
65
|
+
Each variable is matched exactly: `PI_STATS_DISABLE_USAGE_SIDECARS=true` does nothing, only `=1` disables sidecars.
|
|
66
|
+
|
|
67
|
+
## Troubleshooting
|
|
68
|
+
|
|
69
|
+
**Totals look too low, or a session is missing.** Press `u` in the dashboard to force a full rescan and rebuild the index; the cache keys off file stat identity, so a session restored from backup with older timestamps can otherwise be skipped. If the sessions live outside the standard root, add their directory to `PI_STATS_SESSION_DIRS`.
|
|
70
|
+
|
|
71
|
+
**Guardian or other extension usage is missing.** Sidecar reading is skipped entirely when `PI_STATS_DISABLE_USAGE_SIDECARS=1`. Otherwise confirm the writing extension is enabled and that `<agent dir>/<extension>/usage.jsonl` exists; sidecars are only discovered one level below the agent directory.
|
|
72
|
+
|
|
73
|
+
**A model shows under `Tools/summaries` instead of its own row.** That bucket holds nested usage that carries no attributable response model, such as some compaction and branch-summary records. It is counted in the totals either way.
|
|
74
|
+
|
|
75
|
+
**Costs read `$0.00` or look wrong.** Displayed cost is whatever Pi already recorded in the session; `pi-stats` performs no pricing lookup and contacts no billing API. Providers used through a subscription or proxy commonly record zero cost.
|
|
76
|
+
|
|
77
|
+
**The dashboard looks cramped.** Columns collapse onto a labelled continuation line as the terminal narrows. Widen the terminal to restore the single-line layout, or press `e` to switch to compact totals.
|
|
78
|
+
|
|
79
|
+
**Reset everything.** Delete `~/.pi/agent/pi-stats/cache.json` (path follows `PI_CODING_AGENT_DIR`). It is a disposable index and the next `/stats` run rebuilds it from the sessions.
|
|
80
|
+
|
|
48
81
|
## Cache and privacy
|
|
49
82
|
|
|
50
83
|
Sessions remain authoritative. For fast repeat opens, the extension stores one disposable index:
|