millionco/claude-doctor provides a diagnostic tool for Claude Code sessions, analyzing user transcripts to identify behavioral anti-patterns and automatically generate configuration rules. It targets developers and power users interacting with Claude, aiming to improve AI assistant performance, consistency, and adherence to desired behaviors through data-driven insights.

How It Works

This tool processes Claude session transcripts, typically found in ~/.claude/ or specified .jsonl files. It employs a range of detection algorithms to identify structural issues (e.g., edit-thrashing, error loops), behavioral anomalies (e.g., high abandonment rates, excessive corrections), and lexical patterns using AFINN-165 sentiment scoring. The analysis yields actionable signals, which are then used to generate concrete, agent-readable rules for files like CLAUDE.md or AGENTS.md.

Quick Start & Requirements

Installation is achieved via npm: npm i -g claude-doctor, or it can be run directly using npx claude-doctor. Usage includes analyzing all sessions by default, targeting specific session IDs or files, filtering by project (-p), generating rules (--rules), or saving analysis models (--save). No specific hardware, GPU, CUDA, or Python version requirements are mentioned beyond the implicit need for Node.js and npm.

Highlighted Details

• Detects 11 distinct structural and behavioral anti-patterns.
• Generates ready-to-paste rules for agent configuration files (CLAUDE.md, AGENTS.md).
• Utilizes Lexical AFINN-165 sentiment scoring with custom agent tokens.
• Supports saving analysis baselines and project profiles to .claude-doctor/model.json.

Maintenance & Community

No specific details regarding maintainers, community channels (e.g., Discord, Slack), or project roadmap were provided in the README excerpt.

Licensing & Compatibility

The project is licensed under the MIT license. This permissive license generally allows for broad compatibility, including commercial use and integration within closed-source projects without significant restrictions.

Limitations & Caveats

The tool's effectiveness is contingent on the availability and format of Claude session transcripts. Analysis accuracy and the utility of generated rules depend heavily on the volume and representativeness of the historical data processed. Specific limitations regarding unsupported platforms or known bugs are not detailed.