claude-doctor

Analyzes your ~/.claude/ transcripts for behavioral anti-patterns and generates rules for CLAUDE.md / AGENTS.md from your history.

claude-doctor.mp4

Install

npm i -g claude-doctor

Or run directly:

npx claude-doctor

Usage

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

Signals

Structural

Signal	Detection
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	Most sessions have fewer than 3 user messages

Behavioral

Signal	Detection
correction-heavy	20%+ of user messages start with "no", "wrong", "wait"
keep-going-loop	User repeatedly says "keep going" / "continue"
repeated-instructions	Same instruction rephrased within 5 turns (Jaccard >60%)
negative-drift	Messages get shorter and more corrective over time
rapid-corrections	User responds within 10s of agent output
high-turn-ratio	User sends 1.5x+ messages per agent response

Lexical

AFINN-165 sentiment scoring with custom agent tokens (undo, revert, wrong, broken, etc).

--rules

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

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

Based on analysis of 838 sessions. Paste into your CLAUDE.md or 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 haven't drifted.

--save

Writes a model to .claude-doctor/:

• model.json signal baselines and project profiles
• guidance.md agent-readable rules for hooks or CLAUDE.md inclusion

Development

pnpm install
pnpm build
pnpm test

License

MIT