claude-doctor reads your Claude Code transcripts and tells you how the agent failed you

Your session transcripts already know what went wrong

AI coding sessions fail in patterns. The same file gets edited six times, the user types no and wrong all afternoon, the session ends with two messages and an abandoned repo. Everyone senses these patterns; almost nobody measures them. claude-doctor, an npm CLI from MillionCo, does the measuring: it reads the transcripts stored under ~/.claude and reports the anti-patterns inside them, session by session or project by project.

The audience is anyone who uses Claude Code seriously enough to have accumulated history: individual developers auditing their own habits, and teams trying to figure out why their agent sessions feel worse than they should. The tool is diagnostic, not protective; it tells you what happened, and its second act turns that diagnosis into rules you can feed back to the agent.

Three families of signals, all mechanical

The detection logic is deliberately countable. Structural signals look at the shape of a session: edit-thrashing fires when one file is edited five or more times in a session, error-loop when three consecutive tool failures happen without a change of approach, excessive-exploration when the read-to-edit ratio exceeds ten to one. restart-cluster flags multiple sessions started within half an hour, and high-abandonment-rate catches sessions that die after fewer than three user messages.

Behavioral signals watch the conversation itself: correction-heavy counts messages starting with no, wrong or wait, and fires at twenty percent; keep-going-loop spots the user repeatedly typing continue; repeated-instructions catches the same request rephrased within five turns using Jaccard similarity above sixty percent; rapid-corrections means the user replied within ten seconds of the agent's output. A lexical layer runs AFINN-165 sentiment scoring with custom agent tokens such as undo, revert and broken. Every threshold is a published constant, which makes the whole thing arguable, in a good way.

Running it

Install is one npm command, or skip the install entirely:

npm i -g claude-doctor

Running it directly works too, via npx claude-doctor. The usage surface is a flat list of flags:

claude-doctor                     # analyze all sessions (default)
claude-doctor <session-id>        # check a specific session
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

The default run analyzes all sessions. Pointing it at one session id, one transcript path or one project narrows the blast radius, and the JSON flag makes the output consumable by whatever dashboards or scripts a team already runs.

From diagnosis to rules: --rules and --save

The interesting half of the tool is the feedback loop. With --rules, claude-doctor generates paste-ready rules for CLAUDE.md or AGENTS.md derived from your own history, and the README shows the real output, opened by a line stating it is based on analysis of 838 sessions. The generated rules read like scar tissue from the signals: read the full file before editing and make one complete edit; after two consecutive tool failures, stop and change approach entirely; when the user corrects you, stop and re-read their message; complete the full task before stopping; re-read the original request every few turns to check for drift.

The --save flag persists the analysis as a reusable model in .claude-doctor/: model.json holds signal baselines and project profiles, guidance.md holds agent-readable rules suitable for hooks or direct CLAUDE.md inclusion. Diagnosis, baseline and prescription end up as files in your repository rather than impressions in your head.

What the signals cannot see

The thresholds are honest proxies, and proxies fail in known ways. A ten-to-one read-to-edit ratio can mean a thrashing agent, or a legitimate research afternoon in an unfamiliar codebase. Rapid corrections can mean frustration, or an expert steering tightly. The behavioral layer is also language-bound: correction-heavy keys on English words like no and wrong, so non-English sessions will under-report correction patterns by construction.

The tool sees transcripts, nothing else. It cannot judge whether the code produced was good, and the README claims no runtime telemetry. Privacy is likewise a non-story in both directions: every documented operation is a local CLI command writing into .claude-doctor/, and the README documents no upload step anywhere. Treat the output as conversation-level evidence, not code review.

Maintenance and licence

The repository is a pnpm and turbo monorepo with a packages/ layout and changesets wired for releases, but no releases or tags have been published, and the last push was on 2026-04-15, about five months back. One licence wrinkle deserves mention: there is no LICENSE file in the repository tree, while both the README and package.json declare MIT. If your organization requires a licence file before adopting a dependency, this repo will trip that check until the maintainers add one.

Development status is visible in the tooling: a TypeScript native preview dependency, changeset-driven versioning, and a typecheck script. The project looks like a well-run prototype that slowed down rather than an abandoned sketch, but the commit history, not this paragraph, should settle that when you evaluate it.

Against reading your own history by hand

The do-nothing alternative is real: open a few transcript files, squint, and decide the agent needs better prompts. That works for one bad afternoon and stops scaling somewhere around a hundred sessions, which is precisely the point where counts and baselines beat impressions. Team-level agent analytics platforms occupy the same territory from the hosted direction, at the price of sending your transcripts somewhere else.

claude-doctor's niche is the middle: local, scriptable, JSON-emitting analysis of the transcripts you already have, with the opinionated step no competitor takes, turning the diagnosis back into CLAUDE.md rules the agent will actually read next session. If your workflows already treat CLAUDE.md as the control surface for agent behavior, the tool plugs straight into that loop.

Editorial conclusion

claude-doctor fits developers and teams with a real backlog of Claude Code sessions who want their agent friction counted, baselined and converted into CLAUDE.md rules, all locally and scriptably. Skip it if you have only a handful of sessions, if your corrections happen in a language other than English, or if you need code-level quality analysis rather than conversation-level signals. Verify the premise on your own data first: run npx claude-doctor, read one flagged session against the signals that fired, and decide whether the thresholds match how you would judge that session yourself.

Frequently asked questions

Official sources

1. Issues
2. millionco/claude-doctor on GitHub
3. README