pi-doctor

Analyzes your ~/.pi/agent/sessions/ history for behavioral anti-patterns and generates rules you can paste into AGENTS.md or ~/.pi/agent/AGENTS.md.

Use

npx pi-doctor

Or clone and run it locally:

bun ./src/cli.ts

Usage

pi-doctor                     # analyze all Pi sessions (default)
pi-doctor <session-id>        # check a specific Pi session by header id
pi-doctor <path/to.jsonl>     # check a specific session file
pi-doctor -p myproject        # filter to a project path / cwd
pi-doctor --rules             # generate AGENTS.md guidance
pi-doctor --save              # save model to .pi-doctor/
pi-doctor --json              # output as JSON

Defaults

• Reads sessions from ~/.pi/agent/sessions
• Resolves project names from the Pi session header cwd
• Saves learned guidance to .pi-doctor/model.json and .pi-doctor/guidance.md

Signals

Structural

• edit-thrashing: same file edited 5+ times in one session
• error-loop: 3+ consecutive tool failures without changing approach
• excessive-exploration: read-to-edit ratio above 10:1
• restart-cluster: multiple sessions started within 30 minutes
• high-abandonment-rate: many sessions have fewer than 3 user messages

Behavioral

• correction-heavy: 20%+ of user messages start with no, wrong, wait, etc.
• keep-going-loop: user repeatedly says keep going / continue
• repeated-instructions: same instruction rephrased within 5 turns
• negative-drift: messages get shorter and more corrective over time
• rapid-corrections: user responds within 10s of assistant output
• high-turn-ratio: user sends 1.5x+ messages per assistant response

Lexical

Uses AFINN sentiment scoring with extra Pi-specific frustration tokens such as undo, revert, wrong, broken, and keep going.

--rules

Generates ready-to-paste rules from your Pi session history:

## Rules (auto-generated by pi-doctor)

Based on analysis of 838 Pi sessions. Paste into your AGENTS.md.

- Read the full file before editing. Plan all changes, then make ONE complete edit.
- After 2 consecutive tool failures, stop and change your approach entirely.
- When the user corrects you, stop and re-read their message.
- Complete the full task before stopping.
- Every few turns, re-read the original request to make sure you have not drifted.

--save

Writes a model to .pi-doctor/:

• model.json: signal baselines and project profiles
• guidance.md: agent-readable rules for AGENTS.md inclusion or prompt injection

Credits

Adapted from claude-doctor