/doctor used to be a read-only report: run it, get a wall of diagnostic text, fix things yourself. As of v2.1.205 (shipped in the week of July 6–10, 2026), it’s an active checkup that diagnoses and fixes — installation problems, yes, but also the slower kind of rot that accumulates in a Claude Code setup over months of adding skills, MCP servers, and CLAUDE.md instructions you never got around to pruning. It has a new alias, /checkup, which is arguably the more accurate name for what it does now.
This guide covers exactly what changed, what each check looks for, and how the confirm-before-changing flow works — sourced from the official weekly digest and the commands reference.
What Changed: From Read-Only Report to Active Fixer
The old /doctor printed diagnostics and stopped there. You read the output, then went and fixed whatever it found — a stale install, a broken PATH entry — by hand.
The new /doctor (alias /checkup) still starts with a report, but it doesn’t stop there. Per the commands reference, it “diagnoses issues and can fix them,” and the digest confirms the same shift: “/doctor now diagnoses issues and can fix them, instead of printing a read-only report.”
One important nuance: this applies to /doctor run inside a Claude Code session. Run claude doctor from a plain terminal — without starting a session — and it still “prints read-only installation diagnostics.” That distinction matters if you’re scripting health checks in CI or a pre-flight hook, where you want output only, not an interactive fix flow.
Run it from any session with:
> /doctoror the alias:
> /checkupDiagnosing and Fixing Installation Issues
The installation-health side of the check now covers more ground than the old version. Per the commands reference, it checks:
- Duplicate or leftover installs — multiple Claude Code binaries or install paths that can shadow each other and cause version confusion
PATHproblems — the classic “whichclaudeam I actually running” issue- Unparseable settings files — malformed JSON in
settings.jsonor similar config that silently breaks features instead of throwing a clear error - Version currency — checks for a newer version on your release channel
None of this is exotic — it’s the stuff that used to require manually inspecting which claude, diffing settings files, or re-running the installer to figure out. /doctor now surfaces it in one pass and offers to fix what it can.
Flagging Unused Skills, MCP Servers, and Plugins by Context Cost
This is the check most power users will actually care about. Every skill, MCP server, and plugin you’ve installed occupies part of your context window whether you use it that session or not — tool descriptions, skill frontmatter, and server capability lists all get loaded up front. Add enough of them over a few months of experimentation and a meaningful chunk of your context budget is spent on things you stopped using in March.
/doctor now finds “unused skills, MCP servers, and plugins versus their context cost” — meaning it doesn’t just tell you that something is installed, it tells you what it’s costing you to keep it loaded while it sits idle. That reframes the question from “do I still want this?” to “is this worth the tokens it’s eating on every session start?” — a more useful prompt for actually cleaning house.
If you’re not sure which of your MCP servers are the expensive ones, /mcp shows connected server status in the moment; /doctor is the tool for the standing audit across everything you’ve accumulated.
CLAUDE.md Deduplication and Trimming
CLAUDE.md files have a well-known failure mode: they start lean and grow into a dumping ground, because it’s always easier to append a new rule than to go back and ask whether an old one still earns its place. /doctor now attacks this from two angles.
Deduplication. It “deduplicates local CLAUDE.md files against checked-in ones” — catching the case where a personal, uncommitted CLAUDE.md repeats guidance that’s already sitting in the project’s committed version, wasting context on the same instruction twice.
Trimming. For checked-in CLAUDE.md files, it proposes cutting “content Claude could derive from the codebase” — the commands reference is specific about what that means in practice: directory layouts, dependency lists, and architecture overviews are trim candidates, because Claude can reconstruct those by reading the repo. What it explicitly keeps: “pitfalls, rationale, and conventions that differ from tool defaults” — the parts a model can’t infer just by looking at the file tree.
There’s a third piece beyond straight deletion: /doctor “migrates the always-loaded guidance that remains into skills and nested CLAUDE.md files that load on demand.” In other words, instructions that only apply to specific subdirectories or specific tasks don’t need to sit in the root CLAUDE.md, paying a context tax on every single session — they can move into a nested CLAUDE.md or a skill that only loads when it’s relevant.
For a team CLAUDE.md that’s grown past the point anyone wants to read it end to end, this is the first structural cleanup tool that’s actually built into the product rather than something you do by hand during a slow afternoon.
Slow Hooks Detection
Hooks that run on every tool call or every session start are easy to forget about once they’re wired up — until a session starts feeling sluggish and nobody remembers which hook is the culprit. /doctor now flags slow-running hooks as part of the same pass, giving you a concrete lead instead of a vague sense that “things feel slower lately.”
If you’ve added several PreToolUse or PostToolUse hooks over time — linting, formatting, logging, notification pings — this is the fastest way to find out which one is actually adding latency before you start disabling them one by one to isolate it manually.
Extra Checks: Auto Mode and Pre-Approvals
Two smaller items round out the pass, both permission-related rather than diagnostic:
- It offers to make auto mode your default permission mode, if you’re not already running it that way
- It offers to pre-approve frequently denied read-only commands — the ones you keep manually clicking “allow” on because they’re safe but not yet in your allowlist
Neither of these changes anything without you saying yes, which is the same confirm-first behavior that governs everything else /doctor touches.
How the Confirm-Before-Changing Flow Works
The trust-critical detail here is that /doctor is not a silent auto-fixer. It “reports findings first and asks for confirmation before changing anything” — every category above (installation fixes, unused-item removal, CLAUDE.md trimming, auto mode changes, pre-approvals) goes through the same two-step pattern: report, then ask. Nothing gets deleted, trimmed, or reconfigured until you explicitly approve it.
That matters most for the CLAUDE.md trimming feature specifically, since it’s editing a file your whole team may depend on. You see the proposed cuts before they land, not after.
A realistic session might look like this:
> /checkup
Running setup checkup...
Installation
✓ No duplicate installs found
✓ PATH resolves to expected binary
⚠ settings.json contains a trailing comma (unparseable) — fixable
Context usage
⚠ 3 unused skills loaded (~1,400 tokens/session, last used 40+ days ago)
⚠ 1 MCP server connected but never invoked this month (~2,100 tokens/session)
CLAUDE.md
⚠ Local CLAUDE.md duplicates 2 rules already in the checked-in version
⚠ Directory layout section (checked-in) is derivable from the codebase — trim candidate
Hooks
⚠ PostToolUse hook "format-on-save" averaging 4.2s per invocation
Apply fixes? [y/N](Illustrative — actual output formatting may vary by version.)
FAQ
Is /doctor the same as /checkup?
Yes. /checkup is an alias for /doctor — they run the identical setup checkup. Anthropic added the alias alongside the v2.1.205 feature expansion because “checkup” better describes what the command does now that it’s more than a diagnostic printout.
Will /doctor change my files without asking?
No. It reports findings first and asks for confirmation before making any change — installation fixes, CLAUDE.md trims, unused-item cleanup, and permission changes are all opt-in per the official documentation.
Does claude doctor from the terminal do the same thing as /doctor in a session?
Not exactly. claude doctor run from a plain terminal (outside a session) prints read-only installation diagnostics only. The full diagnose-and-fix behavior, including the context-cost analysis and CLAUDE.md trimming, runs when you invoke /doctor or /checkup inside an active session.
How does /doctor know a skill or MCP server is “unused”?
The official docs describe the check as finding unused skills, MCP servers, and plugins “versus their context cost” — it compares what’s loaded against what’s actually been invoked, and surfaces the ones sitting idle relative to the tokens they occupy. Exact lookback windows and thresholds aren’t specified in the public docs.
What does the CLAUDE.md trim keep versus cut? It cuts content Claude could re-derive from the codebase itself — directory layouts, dependency lists, architecture overviews. It keeps pitfalls, rationale, and conventions that differ from tool defaults, since those aren’t recoverable by reading the repo. Guidance that’s only relevant to part of the project can also get migrated into nested CLAUDE.md files or skills that load on demand instead of being deleted outright.
Should I run /doctor regularly, or only when something breaks?
Given that it now covers context-budget waste and CLAUDE.md bloat — not just broken installs — it’s worth running periodically as maintenance, not only when troubleshooting. A setup that’s been accumulating skills and MCP servers for a few months is exactly the case this feature was built for.