claude doctor in your shell checks the installation and changes nothing. /doctor (alias /checkup) inside a session is a bundled skill that audits your skills, MCP servers, plugins, hooks and CLAUDE.md files, and asks before it fixes anything.
The shell version gives you a tidy little report. Version, install method, platform, update channel, the last update attempt, and whether Remote Control is available. Mine ends with "No installation issues found" and a pointer to /doctor for a full checkup that can also fix what it finds. All green, nothing to do.
Then run /doctor inside a session and you get ten checks. Two of them ask whether Claude Code is installed and current. The other eight ask what you did to it.
That gap is the interesting part. The command kept its name and quietly changed its job.
What the /doctor health check covers now
/doctor became a bundled skill in 2.1.203, while claude doctor in the shell kept the old installation check. It reads your settings, your skills, your MCP servers, your plugins, your hooks and your memory files, then proposes changes. Here is the full list, straight from the skill in 2.1.203:
| # | Check |
|---|---|
| 0 | Setup health: installation, settings, agent definitions |
| 1 | Unused skills, MCP servers and plugins |
| 2 | Local CLAUDE.md dedup and contradictions |
| 3 | Trim derivable content from checked-in CLAUDE.md files |
| 4 | Migrate always-loaded CLAUDE.md content to lazy loading |
| 5 | Slow hooks |
| 6 | Context-heavy extensions |
| 7 | Claude Code version |
| 8 | Auto mode as the default permission mode |
| 9 | Pre-approve frequently denied read-only commands |
Checks 0 and 7 are the old health check. Checks 1 through 6 are a context audit. Checks 8 and 9 are something else again, and I'll come back to those.
The accounting in check 6 is specific enough to be useful: it estimates always-resident context per component, breaks out each memory file, and measures your skill and command listing against a budget of roughly 1% of the window. It also tells you its numbers are disk-based estimates and points you at /context for the live measurement, which is a level of honesty I did not expect from a tool selling you its own cleanup.
What changed since 2.1.203
Three changes landed between 2.1.203 and 2.1.270:
- Stale sandbox files (2.1.257).
/doctorwarns about sandbox mask files that a killed session left behind. /skill-doctor(2.1.261). A separate command that shows only your unused skills and what they cost in context. It is the skills half of check 1, and the quicker option when that is all you want to know.- Organization policy (2.1.268).
claude doctornow reports when your organization's policy fails to load, for example behind a proxy.
Why this arrived now
Sonnet 5 shipped with a 1M-token window on 30 June. Opus 5 followed on 24 July with the same. Both are the default in Claude Code for their tier.
Back when the window was 200k, setup rot announced itself. You loaded eleven plugins and a 400-line CLAUDE.md, and by mid-afternoon you were watching the compaction warning and cursing. The wall was annoying, and the wall was also feedback.
At a million tokens almost nobody hits the wall. The rot is still there, it just stopped erroring. Your agent gets a little vaguer, a little slower to start, a little more likely to follow the stale instruction three sessions after it stopped being true. Nothing in the interface tells you, because nothing broke.
So Anthropic shipped a linter for it. That is what checks 1 through 6 are: a linter for the mess that no longer has a symptom. I've argued before that a plugin stack can cost more context than it saves, and this is the vendor conceding the point by building the meter.
The check that edits your memory
Check 3 is the one worth slowing down for. It proposes trimming your checked-in CLAUDE.md by cutting content Claude could derive from the codebase. Directory layouts, dependency lists, architecture overviews: gone, because the agent can read all of that. Pitfalls, rationale and conventions that differ from tool defaults: kept.
The dividing line is exactly right. I've argued the same thing about stale memory, where the file that describes your folder structure is the file that lies to you six weeks later.
What makes me sit up is who draws the line. "Content Claude could derive from the codebase" is the model assessing its own inference, and self-assessment is the one capability these things reliably lack.
It will confidently propose cutting the line that looked redundant and was actually load-bearing, the one that stops it doing the thing it does every single time on this repo. The proposal will read perfectly reasonable. You will not remember why that line was added, because you added it eight months ago after the third incident.
/doctor reports findings first and asks before it changes anything, so you get a diff. Read it like a pull request from a fast, eager junior who has never seen this repo before, which is precisely what it is. The rule about never shipping code you don't understand covers your memory file too. That file is configuration, and configuration outranks code for blast radius per line.
Checks 8 and 9 have an opinion
Check 8 proposes making auto mode your default permission mode, user scope, every project. Check 9 finds read-only commands you keep denying and offers to pre-approve them.
Both are defensible. Check 9 is straightforwardly good: if you've said no to git status forty times, the prompt is furniture. And the skill is careful about check 8, skipping when policy or project settings pin a different mode, noting that the CLI falls back safely if auto mode is unavailable.
Still, notice what happened. A tool called "doctor" now recommends a looser default permission posture as part of a health check. That framing does work, because nobody argues with a diagnostic. If you want auto mode, take it deliberately, with the permission model in your head, and not because a green checklist offered it between a hook timing report and a version bump.
The bit that surprised me
Buried in check 1 is an instruction the skill gives itself: never report a token cost for deferred MCP tools, and never recommend disabling an MCP server to save context when its tools are deferred.
MCP tool schemas now sit behind a search tool by default. Only the name is resident, the schema is fetched on demand. So the standard advice, prune your MCP servers because they eat your window, is mostly obsolete.
The skill knows this and refuses to take credit for savings that would not happen. It still suggests removing servers you never invoke, framed honestly as one less thing to authenticate and maintain.
A cleanup tool that declines to overstate what its cleanup buys you is a good sign about the rest of it.
How I run it
claude doctor from the shell is read-only. Run it whenever something feels off about the install itself.
Neither command looks at the session you are sitting in right now. That has its own meter and its own habits, and it rots on a timescale of hours rather than months.
/doctor in a session is an agent with edit rights on your configuration. I run it roughly monthly, at the start of a session where I still have the patience to read a diff. At the end of a long day the checklist is the last thing between me and a merge, and I would wave the whole thing through.
Accept without much thought: version bumps, slow hook reports, dedup of local memory files against checked-in ones, servers you have genuinely never called. Read line by line: anything touching a checked-in CLAUDE.md, and both permission proposals.
The command that used to tell you the tool was broken now mostly tells you that you are. Ten checks, and eight of them are about decisions you made. That is a worse report to receive and a far more useful one.