Why You Should Run claude doctor

You’ve been using Claude Code for months and it works, mostly. Then something goes odd. A hook that used to fire doesn’t. A setting you’re certain you set has no effect. Search comes back with fewer files than you know are in there. So you shrug, restart, and carry on, because the work is more interesting than the plumbing.

There’s a command that tells you whether the plumbing is sound. Two, actually. I used one of them for a year before noticing the other existed, and they do different jobs.

By the end of this guide you’ll know what each one checks, how to read the output, and where each one is blind.

What you’ll need

• Claude Code, installed and working. Or not working: that’s one of the cases this covers.
• Ten minutes, and a willingness to read the middle of the output rather than the last line.

The two doctors

They’re not interchangeable, and the difference is the whole point.

	claude doctor	/doctor
Where you run it	Your shell	Inside a Claude Code session
What it does	Reports	Reports and offers to fix
Reads settings	Yes, without a trust prompt	Yes
Also checks	—	Extensions, context usage
Works when Claude Code won’t start	Yes	No

The CLI’s own help text puts it plainly: “Check the health of your Claude Code installation. Reads settings files in the current directory without a trust prompt. For a full checkup that can also fix issues, run /doctor in a session.”

Two things in there are easy to skim past.

“Without a trust prompt” means you can point it at a directory you haven’t approved yet and it will still read the settings. Useful when you’ve cloned something and want to know what its .claude/settings.json is asking for before you let it run.

“Can also fix issues” belongs to /doctor alone. The official troubleshooting guidance says it “proposes fixes it can apply after you confirm.” So /doctor is the one you want ordinarily. claude doctor is the one you want when claude itself is refusing to start — which is exactly when a diagnostic inside a session is no use to you.

Run it

claude doctor

No flags. Here’s mine, run while writing this:

Claude Code doctor

Running: native (2.1.220)
Commit: 4073f59596e2
Platform: darwin-arm64
Config install method: native
Search: OK (bundled)
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: success → 2.1.219 (2026-07-24)

Remote Control
Remote Control requires feature-flag evaluation, which is disabled
because DISABLE_TELEMETRY is set. Unset it (or run in a shell without
it) to use Remote Control.
- Feature-flag evaluation disabled (disabled by DISABLE_TELEMETRY)

No installation issues found.

The verdict line is the least useful part

Look at those last two blocks together, because they disagree.

The bottom line says no installation issues found. Four lines above it, the output tells me a whole feature is switched off. Remote Control needs feature-flag evaluation, feature-flag evaluation needs telemetry, and I set DISABLE_TELEMETRY a long time ago for reasons that had nothing to do with Remote Control. Those two facts had never been in the same place at the same time until doctor put them there.

That’s the thing this command is actually good for. Not the verdict line — the middle. My installation is fine by doctor’s own definition, and a capability is off because of a decision I made somewhere else and never revisited.

It’s the same trap as a script exiting zero. Exit zero tells you the thing ran, not that it did what you meant. No installation issues found tells you nothing failed a specific set of checks, not that your setup is doing what you think.

If you take one habit from this guide: read upward from the verdict.

What it checks

The lines are mostly self-explanatory, with two worth dwelling on.

Install method and path. If you’ve ever installed Claude Code more than one way — npm once, native later, maybe a Homebrew attempt in between — this tells you which one is actually running. Two installs where you assumed one explains a surprising amount of odd behaviour.

Search. Mine says OK (bundled), so it’s using the ripgrep that ships with Claude Code. Say you’ve switched to your own ripgrep by setting USE_BUILTIN_RIPGREP=0. This line is how you check it took. The docs tell you to look for “the path of your system ripgrep instead of OK (bundled).” A setting you believe is applied, but isn’t, causes more trouble than one you know is missing.

Auto-update channel matters if you’re chasing a fix that shipped recently, or avoiding one that broke something.

What it cannot see

Here’s where I’d push back on treating this as an audit.

The clearest example sits in Anthropic’s own documentation. On WSL, reading across filesystems is slow. Search returns fewer results than it should. And the docs say it plainly: “claude doctor shows Search as OK in this case.”

So there’s a documented state where search is degraded and doctor calls it healthy. Not a bug, and not hidden — it’s in the manual. The check asks whether ripgrep is present and runnable. It is. Whether your queries come back complete is a different question, and doctor never asks it.

That’s worth keeping as a general habit. Before you trust a green light, ask what that particular light is wired to.

The other blind spot is everything above the installation. Doctor checks that Claude Code is correctly installed. It doesn’t check whether what you’ve added to it makes sense.

I found that out doing a clear-out of my own setup earlier this year. Some of what turned up:

• Marketplaces registered that were dead or empty, still being consulted at startup.
• Plugins installed from a legacy source that had been superseded, so I was pinned to old copies without knowing.
• One plugin installed twice.
• Another with an official replacement that I’d never switched to.
• A tool I’d “uninstalled” months earlier that had never been a managed plugin at all — so its agents, commands, hooks and a SessionStart entry were all still sitting there, quietly loading.
• A pile of Syncthing conflict files under ~/.claude, because that directory is replicated between two machines and nothing was tidying up after it.

Doctor reported no installation issues throughout. It was right. None of that is an installation issue — it’s an accumulation issue, and there’s no built-in command for it. That layer needs looking at by hand, or with something you’ve written yourself.

The next rungs

When doctor says everything’s fine and something is still wrong, these are what I reach for next:

• /mcp — MCP server status. Doctor won’t tell you a server failed to connect.
• claude --safe-mode — starts a session with every customisation disabled. If the problem disappears, it’s yours: a plugin, an MCP server, or a hook. Fastest way to split “Claude Code is broken” from “something I installed is broken.”
• /doctor — the fuller checkup, including extensions and context usage, with fixes it can apply once you say yes.
• /heapdump — for memory that keeps climbing. One caution the docs are firm about: the snapshot contains every string in the process, so don’t attach it to a public issue. Share only the -diagnostics.json file.

Limitations worth knowing

The WSL search case above is the one to remember, and it’s the docs’ own example rather than my speculation.

Beyond that: claude doctor reads the settings files in the current directory. Run it somewhere else and you may get a different answer about settings, though the install-level lines stay the same. If you’re diagnosing project-specific behaviour, run it in that project.

And it’s a snapshot. It tells you the state now, not what changed last Tuesday to make things odd. For “settings not applying, hooks not firing, MCP servers not loading,” the configuration-debugging path is the right one — doctor will happily report a healthy install underneath a hook that never fires.

The bigger picture

Run this because a tool you use every day drifts, and almost none of that drift announces itself. Versions move. Install methods stack up. A setting you added for one reason quietly switches off something unrelated. And the whole thing keeps working well enough that you never look.

Ten seconds in a shell gets you the install-level picture. It won’t cover everything you’ve bolted on since — and that’s the part most likely to have gone stale. It’s also where a clean bill of health, from a check that wasn’t looking, misleads you most.

So run it, because it’s cheap. Read the middle, because that’s where the information is. And treat “no issues found” as the start of the question rather than the end of it.