claude-doctor
v0.0.3
Published
Analyze Claude Code transcripts for quality signals, sentiment drift, and behavioral anti-patterns.
Maintainers
Readme
claude-doctor
Analyzes your ~/.claude/ transcripts for behavioral anti-patterns and generates rules for CLAUDE.md / AGENTS.md from your history.

Install
npm i -g claude-doctorOr run directly:
npx claude-doctorUsage
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 JSONSignals
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.jsonsignal baselines and project profilesguidance.mdagent-readable rules for hooks or CLAUDE.md inclusion
Development
pnpm install
pnpm build
pnpm testLicense
MIT
