GuidesClaude Code

Run /doctor before you blame the model

By Stephen Thorn · 2 minute read ·

Claude Code acting up? Run /doctor before you blame the model

/doctor is a checkup of your Claude Code setup. It finds leftover installs, out-of-date versions, settings files that won't load, skills and tools you're paying for on every message without using, and lines in your CLAUDE.md that Claude could work out on its own. Claude reports what it finds first, and changes nothing until you say yes.

What you need

  • Claude Code v2.1.205 or later, when /doctor became the full checkup. The CLAUDE.md trim came in v2.1.206. Run claude update if you're behind.

  • A few minutes to read the report before you say yes to anything.

Step 1: run it

Type /doctor in a Claude Code session. /checkup does the same thing.

Want a report without starting a session? Run claude doctor in your terminal. That version only reads; it doesn't change anything.

Step 2: read the report

It checks 4 areas:

  • Installation: Duplicate or leftover installs, PATH problems, settings files it can't read, and whether a newer version is available

  • Extensions: Skills, MCP servers (connected tools) and plugins you don't use, compared with what each costs you in context, plus slow hooks. It also offers to move instructions that load on every message into skills that load only when needed

  • CLAUDE.md: Checked-in CLAUDE.md lines Claude could work out from your files. It proposes trimming them

  • Permissions: An offer to make auto mode your default permission mode

Step 3: decide what to say yes to

Claude asks before it changes anything, so you can take the fixes one at a time.

Usually a yes:

  • Removing leftover installs and fixing a settings file it can't read.

  • Updating to the newer version.

  • Trimming CLAUDE.md. Read the diff first, and keep any line that's a rule Claude couldn't guess from your files.

Think first:

  • Turning off skills, plugins or MCP servers it flags as unused. Unused so far doesn't always mean unneeded.

  • Making auto mode your default. In auto mode, a second model checks Claude's actions and Claude runs them without asking you. The PERMS guide shows how to check your mode and block the commands you never want run.

The mistake to avoid

Saying yes to everything in one go. Most fixes are housekeeping, but the auto mode offer changes how Claude Code asks you before it acts. Take that one on its own, after you've read the PERMS guide.

One more thing: /doctor reads your real setup, so the report lists your own skills, plugins and connected tools. Crop them out before you share a screenshot.