Claude Doctor
https://github.com/millionco/claude-doctor- Category
- Developer Tools
- Rank
- No. 1039Tools index
- Pricing
- Open Source
- Type
- TOOL
- Builder
- millionco
- GitHub
- 617 stars
- Date
About
Diagnostic tool for Claude Code sessions. Inspect token usage, MCP servers, and session health to debug your workflow.
What it does
Claude Doctor reads local Claude Code transcript histories and turns recurring interaction failures into actionable guidance. It identifies patterns such as repeated edits, unproductive command retries, excessive reading, user corrections, interruptions, and deteriorating conversation tone. It can assess one session or aggregate projects, then print terminal reports, emit JSON, generate agent rules, or save a reusable behavior model.
Why it's ranked here
The tool has a clear, practical feedback loop: observed transcript patterns become specific rules for future agent sessions. Its detectors use documented thresholds, reports expose supporting signals, and machine-readable output supports further processing. The verdict is still mixed because session health relies on coarse heuristics and sentiment scoring, not proof that an agent actually misunderstood or failed.
What's good
The analysis covers both tool behavior and conversation behavior. It catches repeated file edits, consecutive failures, read-heavy workflows, rapid corrections, repeated instructions, interruptions, and short-session clusters. Single-session timelines surface problem turns, while aggregate reports compare projects. Generated guidance maps detected patterns to concrete changes, and saved baselines let later checks flag recurring historical issues.
Tradeoffs
Many conclusions depend on fixed thresholds and lexical cues, so valid exploration, terse feedback, or fast replies can look unhealthy. Long user messages are excluded from behavioral analysis, malformed transcript lines are silently ignored, and project matching uses decoded directory names. The supplied implementation analyzes local transcript records; it does not show dedicated MCP server inspection or token-usage reporting despite those adjacent diagnostic needs.
How to use it well
Use it after enough Claude Code work has accumulated to reveal repeated habits, or inspect a troublesome session immediately. It best serves engineers tuning agent instructions and comparing behavior across projects. Treat generated rules as proposals to verify against real transcripts, especially sentiment-based warnings. Keep separate tools for MCP configuration checks, token accounting, runtime tracing, and general system diagnostics.
Technical notes+
The TypeScript CLI entry in packages/cli/src/cli.ts uses Commander and supports session IDs, JSONL paths, project filtering, JSON output, rule generation, and saved models. packages/cli/src/parser.ts streams JSONL with readline and skips malformed records. packages/cli/src/reporter.ts coordinates project indexing and signal detectors, while packages/cli/src/model.ts writes model.json and guidance.md under .claude-doctor. packages/cli/src/index.ts also exposes parser, detector, reporting, suggestion, model, and visualization functions as a library surface. packages/cli/vite.config.ts builds ESM declarations for Node 18.
Observed
- License
- MIT
- Primary language
- TypeScript
- Install surface
- Global npm installation or direct execution through npx
- Interfaces
- Command-line interface plus exported library functions
- Runtime target
- Node.js 18, packaged as ESM
- Package management
- pnpm workspace tooling with Turbo build, test, and typecheck scripts
Read from README.md, package.json, packages/cli/vite.config.ts, packages/cli/src/cli.ts, packages/cli/src/viz.ts, packages/cli/src/index.ts, packages/cli/src/model.ts, packages/cli/src/parser.ts, packages/cli/src/indexer.ts, packages/cli/src/types.d.ts, packages/cli/src/reporter.ts, packages/cli/src/vendor.d.ts, packages/cli/src/constants.ts, packages/cli/src/suggestions.ts, packages/cli/src/signals/sentiment.ts.
What it can do
Inspect token usage in Claude Code sessions
Claude Code session data → Token usage metrics and statistics
Monitor MCP server status
MCP server connections → Server health status and availability reports
Analyze session health metrics
Claude Code session information → Session health diagnostics and status indicators
Debug workflow issues
Workflow execution data → Debugging information and error analysis
Track session performance
Session activity logs → Performance metrics and bottleneck identification
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.