beginner 20 minutes

What is claude doctor? How to run it and what /doctor does

claude doctor checks your Claude Code install from the terminal; /doctor, in a session, also offers fixes. Learn to run both and read what the report says.

A boxy yellow robot lies on an examination table while two doctor robots check it, one with a stethoscope labelled CLAUDE DOCTOR and one with a clipboard labelled /DOCTOR; a green dog shines a flashlight.
You'll be able to
  • choose between claude doctor and /doctor for the problem in front of you;
  • run claude doctor and read the lines above its verdict;
  • name two things doctor can’t see, and the check to run instead;
  • use claude --safe-mode to tell a Claude Code problem from one you installed.
Who it’s for
people who use Claude Code, whether it’s working or not. This guide is part of the Claude Code strand, because both commands are built into Claude Code.
Time
about 20 minutes, including the exercise (an estimate).

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, and 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.

claude doctor is a command that checks your Claude Code installation and settings from the terminal. Type it in your terminal and it prints a read-only report on your installation and settings files, without starting a session. There’s also a second command, /doctor. I used one of them for a year before noticing the other existed, and they do different jobs. The second, /doctor, runs inside a Claude Code session and also offers to fix what it finds.

Both commands are built into Claude Code, so this guide is for people who use it, whether it’s working or not. Which one do you run when something is odd, and what is the report telling you?

Part 1 of 4 Learn

The two doctors

claude doctor/doctor
Where you run itYour shellInside a Claude Code session
What it doesReportsReports and offers to fix
Reads settingsYes, without a trust promptYes
Also checks—Extensions, CLAUDE.md files, permissions, plan usage
Works when Claude Code won’t startYesNo

You can also type /checkup instead of /doctor, if you find that easier to remember.

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 parts of that help text need explaining.

“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. Anthropic’s troubleshooting page 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.

Pick a symptom to see which one to run.

Which doctor?

Pick what’s going wrong. You’ll see which command or page to use, where to run it, and why.

What’s going wrong?

Use

claude doctor

In your terminal, without starting a session.

Why

/doctor needs a working session, and you don’t have one. claude doctor prints a read-only report on your installation and settings files without starting a session.

If that doesn’t fix it

Read the lines above the verdict. “No installation issues found” can appear a few lines below a line saying a feature is switched off.

This page sends nothing anywhere. It doesn’t run any commands.

How to read this

claude doctor runs in your terminal. It prints a read-only report on your installation and settings files, without starting a session.

/doctor runs inside a Claude Code session. It reports and offers to fix what it finds.

Neither one sees everything. For some problems the right check is another command, a page in Anthropic’s docs, or a search you run yourself.

How to run claude doctor

In your shell, type:

claude doctor

No flags. Here’s mine, run while writing the first version of this guide in July 2026:

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.

Your lines will differ. On version 2.1.316 (checked 5 November 2026), the report also shows how Claude Code was installed by a package manager, the install path, and lines for managed settings and organisation policy, and it closes by pointing you to /doctor for a full checkup.

Read upward from the verdict

With a report like that in front of you, take the verdict and the Remote Control lines 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, and it’s in the middle of the output, above the verdict. 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.

No installation issues found means the install passed doctor’s specific checks, and those checks don’t cover what your setup does day to day.

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

What claude doctor checks

Anthropic’s CLI reference describes the command as printing “read-only installation and settings diagnostics from the terminal without starting a session, including install health, settings-file validation errors, and Remote Control eligibility.” Three lines in the report are worth stopping at.

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 is hard to spot without checking this line.

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

What claude doctor cannot see

Doctor isn’t a full audit of your setup.

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

Note

Anthropic’s troubleshooting page lists this case under “Slow or incomplete search results on WSL”. Its fixes are to search more specific folders or file types, move the project to the Linux filesystem (under /home/), or run Claude Code natively on Windows.

So there’s a documented state where search is degraded and doctor calls it healthy. The check reports that search works, and it does. Whether your queries come back complete is a different question, and doctor never asks it. On WSL, search for a file you know is there before you trust Search: OK.

The other blind spot is what you’ve added on top of the installation. claude 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 in 2026. 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, and that was accurate: all of it came from things I’d added, and claude doctor doesn’t check those.

Since then, /doctor inside a session has started checking some of what you’ve added. Anthropic’s skills page lists what it now looks at: skills, MCP servers and plugins you don’t use and how much context each takes up, hooks that are slow, and CLAUDE.md files that repeat each other.

For the instructions themselves, /doctor prompt-audit checks them. It reads your CLAUDE.md, AGENTS.md, rules, skills, commands and subagents, and looks for “instructions written for older models, references to files or commands that don’t exist, and files that contradict each other.” You get a report with proposed edits, and nothing changes until you ask. It needs version 2.1.283 or later.

Neither /doctor nor /doctor prompt-audit is documented as catching everything on my list, such as a dead marketplace or a pile of sync conflict files. Use them first, then look through the rest by hand.

It reads the current folder, and shows the state now

The checks it does make depend on where you run it: 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.

It’s also a snapshot of the state now, and what changed last Tuesday to make things odd isn’t something it shows. For settings not applying, hooks not firing or MCP servers not loading, Anthropic’s Debug your configuration page is the right path: doctor will report a healthy install underneath a hook that never fires.

When doctor says fine and something’s still wrong

When the report is clean and something still isn’t working, I check these next:

  • /mcp shows MCP server status. claude doctor won’t tell you a server failed to connect.
  • Your CLAUDE.md file. If Claude keeps ignoring your project’s conventions, check what it’s actually being told before you suspect the install.
  • claude --safe-mode starts a session with your customisations disabled. If the problem disappears, one of your customisations is involved: your CLAUDE.md, a skill, plugin, hook, MCP server, or a custom command or agent. It’s the fastest way to split “Claude Code is broken” from “something I installed is broken.”
  • /hooks lists every hook registered in the session, so a hook you wrote that isn’t listed wasn’t loaded.
  • /context shows what’s in the context window, including whether your CLAUDE.md loaded.

The last two come from Anthropic’s Debug your configuration page, which also covers the common causes.

Part 2 of 4 Practise

Try it on your own work

  1. In your shell, go to a project folder and run claude doctor.Result a report that ends with a verdict line, with your version on the Running line and lines for how Claude Code was installed.
  2. Read upward from the verdict. Note any line that says something is disabled, off or unavailable.Result a short list, possibly empty, of lines that need a decision from you.
  3. Run claude doctor again from your home folder.Result the install lines are the same. Doctor reads each folder’s settings, so settings-related lines can differ.
  4. Open a Claude Code session in the project and run /doctor.Result a checkup covering installation, settings, extensions, CLAUDE.md files and permissions. If it proposes a fix, it asks you to confirm before applying it.
  5. Run /doctor prompt-audit.Result a report on your instruction files, listing any outdated or contradicting instructions it finds, with proposed edits. Your files stay as they are until you ask for the edits.
  6. If something has been odd, start claude --safe-mode and try it again.Result if the problem goes away, one of your customisations is involved (CLAUDE.md, a skill, plugin, hook or MCP server); if it stays, look at Claude Code itself, your settings or your environment.
  7. Run /mcp.Result the status of each MCP server. A server that failed to connect shows here and never appeared in the claude doctor report.
  8. Run /hooks and compare the list with the hooks you expect.Result the hooks that actually loaded. If one you wrote is missing, Claude Code never loaded it, and claude doctor doesn’t list hooks.

Part 3 of 4 Check

Check yourself

Claude Code won't start after an update. Which doctor do you run?

claude doctor, from your shell. /doctor needs a working session, and you don’t have one.

Doctor ends with "No installation issues found", but a few lines up it says a feature is disabled because of an environment variable you set. Is your setup fine?

The installation passes doctor’s checks, and the feature is still switched off. Decide whether you still need that environment variable, or whether you’d rather have the feature, and change one of them.

A hook you wrote stopped firing, and `claude doctor` reports no issues. What do you check next?

Open a session and run /hooks. If your hook isn’t in the list, Claude Code never loaded it, and Anthropic’s Debug your configuration page lists the usual causes, such as a hook defined in a standalone file or a matcher written as an array. If it is listed, the matcher is the next thing to check. claude doctor flags some invalid settings, such as a matcher written as an array, but it doesn’t show you which hooks loaded.

On WSL, search in a project under /mnt/c/ keeps missing files you know are there, and doctor shows Search as OK. What do you do?

Don’t trust the OK: doctor only checks that ripgrep runs, and Anthropic’s docs list this exact case. Their fixes are to search more specific folders or file types, move the project to the Linux filesystem (under /home/), or run Claude Code natively on Windows.

Since you installed a plugin, Claude Code has been slow to start, and `claude doctor` reports no issues. What's your next step?

Run /doctor in a session first: it looks at unused extensions and slow hooks, which claude doctor doesn’t. Then start a session with claude --safe-mode. If it starts quickly there, one of your customisations is involved, and the plugin you just added is the first to check: disable it and start normally again.

Part 4 of 4 Keep

Keep this

Run it when something’s odd, and read upward from the verdict

  • Run claude doctor when Claude Code won’t start, and /doctor when it will.
  • Read the lines above the verdict before you believe the verdict.
  • Run it in the project you’re diagnosing, because it reads that folder’s settings.
  • When doctor is clean and something is still wrong, try /mcp, /hooks, /context and claude --safe-mode.
  • Run /doctor and /doctor prompt-audit to check what you’ve added to Claude Code, then look by hand at anything they don’t cover, such as marketplaces.
  • If a hook doesn’t fire, run /hooks to see whether it loaded, because claude doctor doesn’t list hooks.
  • If a setting has no effect, use the Debug your configuration page.
  • If search misses files on WSL, search for a file you know is there, because Search: OK only means ripgrep runs.

In the Kit Library, members can get a one-page symptom card and a prompt that has Claude Code check your hooks and settings files and report back without changing anything.