Pi Health Check — a continuous optimization ritual for the pi setup

[huaxel]

Destination

A manual on-demand, agent-assisted pi health check ritual that covers performance and cost review, configuration hygiene (detecting cruft and drift), and reliability assessment — delivered as a just pi-healthcheck task that produces a dual-format (terminal + JSON) report. The ritual identifies issues and recommends action but does not auto-fix.

Notes

• Domain: Pi (coding agent) configuration, extensions, packages, models, cost tracking, session management
• Skills: Systematic debugging for crash/failover patterns; wayfinder for decision tickets
• Dotfiles repo is source of truth — ~/dotfiles/pi/agent/ is canonical, ~/.pi/agent/ contains legacy stale copies; PI_CODING_AGENT_DIR is the runtime mechanism
• Agent preference: Subagent over workflow
• Report format: Compact terminal summary (5 grades A–F) + rich JSON for machine consumption

Decisions so far

• Health Check Data Sources — Catalogued all pi data sources: dynamic-footer observability (per-turn tokens/cost/TPS), crash/failover logs, session storage (523 MB across 89 project dirs), 11 extensions, 18 npm packages, config files with significant drift between dotfiles and runtime
• Observability Pipeline Status — Root cause: trim({ keepLast: 10 }) in dynamic-footer intentionally caps history to 10 sessions; recommendation is to increase to 200+ and make configurable
• Session Storage Audit — 522 MB total, 69 orphaned worktree sessions (196 MB, 38%), 281 files >30 days old (183 MB); 73% safe to auto-prune in 3 phases
• Crash and Failover Pattern Analysis — 1 crash (context compaction at 175k tokens), failover is proactive load-balancing across 2 accounts (sub-2 used 58%), only 1 quota-exhaustion event in 9,606 requests
• Config Sync Investigation — PI_CODING_AGENT_DIR makes dotfiles the runtime source of truth; ~/.pi/agent/ is largely stale/legacy; drift detection should compare against what PI_CODING_AGENT_DIR loads
• Config Drift Detection Approach — Compare settings.json, models.json, trust.json, extensions/subagent/config.json via structured key-level Node.js diff. 7 drift categories with severity levels. Exclude auth.json and volatile files. Dual-format report.
• Health Check Output Design — Terminal report: 5 grades (A–F) for Cost & Performance, Config Hygiene, Session Storage, Reliability, Observability; one-page summary with critical items. Rich JSON with full findings, grades, and recommendations. Dual-format output from just pi-healthcheck.

Not yet specified

The map is fully specified — all decisions needed to start building have been made.

Out of scope

• Auto-fix — report only
• Continuous/scheduled runs — manual on-demand
• General pi feature work