Claude Code /checkup: the enhanced /doctor, explained

TL;DR

• /checkup is /doctor’s alias, not a new command. As of the v2.1.205 release (July 8, 2026): “/doctor is now a full setup checkup that can diagnose and fix issues; /checkup is its alias.” Type either one.
• It targets seven kinds of accumulated cruft: duplicate CLAUDE.md content, unused skills/MCPs/plugins, an unsplit root CLAUDE.md, slow hooks, a stale Claude Code version, auto mode being off, and read-only commands you keep re-approving.
• Nothing changes without your OK. It reports findings, proposes a plan, and waits for confirmation — settings edits are one-line toggles, and CLAUDE.md edits land in your working tree for a git diff review before you commit.
• It doesn’t invent capability. Everything it automates already existed as a manual step or a narrower skill (/permissions, /hooks, /plugin, /mcp, /fewer-permission-prompts) — jump to manual equivalents if you want to do it by hand.

What /checkup actually is

/checkup is Claude Code’s built-in setup-cleanup command. Run it and Claude Code audits your current configuration — CLAUDE.md files, installed skills, connected MCP servers, plugins, hooks, and your permission-denial history — then proposes a single confirmable plan to fix what it finds.

The framing detail that’s easy to get wrong: /checkup is not a new, separate feature bolted onto Claude Code. It is the existing /doctor command, rebuilt. The changelog entry for v2.1.205 (July 8, 2026) states it directly:

“/doctor is now a full setup checkup that can diagnose and fix issues; /checkup is its alias.”

Before this release, /doctor was a narrower health check — it verified your installation, settings JSON, MCP configuration, and context usage, showed a pass/fail list with status icons, and let you press f to apply straightforward fixes. That’s still how Claude Code’s troubleshooting docs describe it. The July 8 release folds a second, more opinionated job into the same command: not just “is this broken,” but “is this bloated, duplicated, or stale, and should I clean it up.” /checkup is the alias that signals which job you mean.

Why it exists

Two things converged around the same week. First, Claude Code setups accumulate cruft the way any long-lived config does: a project’s CLAUDE.md grows past the point anyone re-reads it, a skill gets installed for one task and never removed, an MCP server stays connected after the project that needed it wraps up. None of that is a bug — it’s just what happens over months of real use, and until now nothing swept it up automatically.

Second, a chunk of the power-user community had already started doing this by hand, aggressively. The day before /checkup shipped, Matt Pocock published a public teardown of Claude Code’s default system prompt, proxying his own sessions to see exactly what gets sent on every request:

Ben Tossell followed up with his own version — a shell alias that swaps in a stripped, “pi-style” system prompt file entirely. The trade was real: less waste, but also a hand-rolled setup that stops tracking Claude Code’s own updates. It is worth flagging the risk in editing the system prompt this directly: it reads as customizing the harness rather than configuring it — the kind of change a provider could reasonably restrict later. A first-party command sidesteps that gap entirely.

Then, on July 8, Boris Cherny — the engineer who created Claude Code — announced the supported version of the same idea:

/checkup is Anthropic’s answer to the same complaint, shipped through the supported command surface instead of a proxy and a hand-edited settings file. You get a chunk of the same token savings without maintaining a fork of your own system prompt.

What it cleans up

Cherny’s thread lists seven categories. Here is what each one actually addresses, and the manual lever it automates (full mapping in manual equivalents below).

1. Clean up unused skills, MCP servers, and plugins. Every enabled skill, connected MCP server, and installed plugin adds to what loads into your context at session start, whether you use it or not. /checkup finds ones you haven’t actually used and proposes disabling them — the same job /plugin disable and /mcp disable do one at a time.
2. Dedupe your local CLAUDE.md against the checked-in one. Personal memory (~/.claude/CLAUDE.md) and project memory (the checked-in CLAUDE.md) can drift into saying the same thing twice as both get edited over time. /checkup finds the overlap and proposes trimming the duplicate.
3. Split a bloated root CLAUDE.md into nested files (+ skills). Claude Code loads nested CLAUDE.md files by directory, so a section that only matters inside api/ doesn’t need to sit in the root file every session loads in full. /checkup proposes moving such sections out — see CLAUDE.md vs AGENTS.md vs Skills for how nested loading and skills compose.
4. Turn off slow hooks. Hooks run on every matching tool event; one written carelessly — a synchronous network call, an expensive lint on every edit — taxes every turn of every session, silently. /hooks lists what’s configured; /checkup profiles them and proposes disabling the slow ones.
5. Update Claude Code to the latest version. The behavior this guide describes is gated behind a version number in the first place. /checkup folds a version check into the same pass, alongside the kind of install repair the real example below demonstrates.
6. Enable auto mode by default. Auto mode routes tool calls through a classifier that blocks anything irreversible, destructive, or aimed outside your environment, and approves the rest without a prompt. Turning it on is one settings change most users never make on their own, because they don’t know it exists.
7. Pre-approve frequently denied read-only commands. Deny the same safe cat or ls-style command enough times and you’re adding friction to your own workflow. This is close to what the standalone /fewer-permission-prompts skill already did — scan transcripts for common read-only Bash/MCP calls, write a prioritized allowlist. /checkup folds that pattern into the general sweep, using the same “Recently denied” data /permissions already tracks.

Cherny’s thread adds “a few other goodies” without specifics. Treat the seven above, plus the install-health checks inherited from the original /doctor, as the confirmed floor — not a ceiling.

What running it looks like

Type /checkup (or /doctor — same command) and Claude Code runs its scan before proposing anything. Cherny posted a real example from his own machine in the same thread:

That screenshot shows the actual shape of the interaction. Cherny’s own setup had a broken claude launcher (a test run had overwritten it), 38 project skills that had never fired across 2,345 sessions, and a CLAUDE.md loading roughly 10,000 tokens every session. /checkup’s report led with the diagnosis in plain language, then offered four ways to respond:

1. Clean up everything (recommended) — the consolidated fix, spelled out: repair the launcher, disable the unused plugins, MCP server, and leftover skill, turn off the 38 unused project skills, and slim CLAUDE.md by moving low-value content to lazy loading.
2. Let me pick — break the same groups apart (install repair, unused plugins/MCP, unused skills, CLAUDE.md slimming) and choose individually.
3. No, keep everything — report only; nothing changes.
4. Type something / chat about it — for anything in between the first three.

Two things worth noting about that specific run. It surfaced only four of the seven general categories — no hook, permission, or version-update findings, because none applied to that repo at that moment. /checkup reports what’s actually present in your setup, not a fixed checklist run in full every time. And the plan explicitly commits to reversibility: settings changes are one-line toggles, and CLAUDE.md edits land in your working tree for a git diff review before you commit anything — nothing is silently pushed.

Before / after

What each category looks like left alone versus after a pass, based on the categories Cherny’s announcement and example both confirm:

When to run it

• Onboarding a repo you didn’t set up. Inherited CLAUDE.md and skills you don’t know the history of are exactly what a fresh audit is for.
• When context feels tight or responses feel slower. A bloated setup eats into the same budget your prompt and files compete for — check /context first, then run /checkup if a lot of it is skills, MCP tool definitions, or memory files.
• Before a token-spend review. If you’re chasing Claude Code cost down, pair this with effort levels: /checkup cuts what loads before you type a single message; /effort controls how hard the model thinks after you do. Different levers, same bill.
• Periodically, on any long-lived repo. Treat it as a maintenance habit, not an emergency-only tool — a quarterly pass catches drift before it becomes a rewrite.
• Right after a major Claude Code version bump. New capability sometimes exposes misconfiguration that was invisible before.

Manual equivalents

None of this is new capability — /checkup is a bundler, not an inventor. If you’d rather do one thing by hand than run the whole sweep, here’s the exact manual lever for each item:

Item seven is worth calling out specifically: it already existed as its own skill, /fewer-permission-prompts, which does almost exactly what /checkup’s seventh item describes — scan your transcripts, write a prioritized allowlist. /checkup absorbs that pattern into the broader pass instead of replacing it outright.

The confirmation step

“Confirms with you before making any changes” is doing real work in Cherny’s announcement, and it maps to two distinct safety nets, not one. Settings changes — disabling a plugin, flipping on auto mode, pre-approving a command — are one-line toggles you can reverse just as easily. CLAUDE.md edits are file edits: they land in your working tree, not your git history, so the actual checkpoint is the ordinary git diff you’d run before any commit.

The menu also isn’t all-or-nothing by force. “Let me pick” breaks the plan into groups so you can accept the CLAUDE.md slimming without also disabling a skill you’re unsure about, in the same run.

Gotchas, one day in

/checkup is one day old as of this guide. There’s no issue tracker history yet, so here’s what we’d flag from the verified announcement and example alone — not from months of bug reports we don’t have:

• “Unused” is a heuristic, not a certainty. See the callout above — review the proposed plan, don’t rubber-stamp it.
• The DIY alternative it displaces carries a real risk /checkup avoids. Editing your own system prompt or launch flags, as the Pocock/Tossell thread above shows people already doing, is a bigger customization of the harness than the supported flags Claude Code exposes — and at least one reply flagged exactly that risk. /checkup runs through the same supported command surface as everything else in this guide, which is the real advantage over hand-editing your prompt file, not just convenience.
• We haven’t verified every one of the “few other goodies” Cherny mentioned. Treat the seven listed items, plus the install-health checks inherited from the original /doctor, as the confirmed floor.
• Expect the exact wording to keep shifting. The screenshot groups findings into four categories; the announcement lists seven. Anchor anything you repeat elsewhere to the v2.1.205 changelog line, not to this guide’s phrasing, until the feature settles past its first week.

Community signal

The discourse around /checkup, a day in, is concentrated on X — Cherny’s two-tweet announcement thread, its quote-tweets, and the Pocock/Tossell system-prompt threads it answers (see Why it exists above). No dedicated Reddit or Hacker News thread had formed as of this writing; give it a few days once more people run their first pass. One more reaction worth surfacing, from the same system-prompt-stripping moment /checkup responds to:

That’s the length people were already going to — a custom launcher alias that both swaps the system prompt and skips permission checks entirely. It shows the appetite /checkup is aimed at, and why a supported, confirm-before-you-commit command is the safer version of the same instinct.

Who this is for

The verdict

Frequently asked questions

Glossary

• /checkup — alias for the enhanced /doctor command; runs a setup audit and proposes cleanup.
• /doctor — Claude Code’s original diagnostic command; as of v2.1.205 it also fixes, not just reports.
• CLAUDE.md — the memory file Claude Code loads into context at session start; exists at user, project, and nested-directory scope.
• Nested CLAUDE.md — a CLAUDE.md placed inside a subdirectory; loads only when Claude is working in that part of the repo.
• Skill — a bundled, on-demand capability Claude Code can load mid-session, such as the /fewer-permission-prompts skill referenced above.
• MCP server — a connected process exposing tools or resources to Claude Code over the Model Context Protocol.
• Plugin — an installable bundle of commands, skills, and/or MCP servers.
• Hook — user-defined code that runs automatically on a tool event, such as before or after a file edit.
• Auto mode — a permission mode that approves routine tool calls via a classifier instead of prompting for each one.
• Permission classifier — the component behind auto mode that blocks irreversible, destructive, or external actions and lets the rest through.
• Allowlist — the set of commands pre-approved in permissions.allow, so Claude Code stops asking about them.
• Context window — the finite token budget available to a session; CLAUDE.md, tool schemas, and loaded files all count against it.

Sources

• Primary — Claude Code changelog, v2.1.205 entry (July 8, 2026): code.claude.com/docs/en/changelog
• Primary — Commands reference (/doctor, /permissions, /plugin, /mcp, /hooks, /memory, /fewer-permission-prompts): code.claude.com/docs/en/commands
• Primary — Troubleshooting and Auto mode configuration docs: troubleshooting · auto-mode-config
• First-party — Boris Cherny (Claude Code creator) announcement thread: @bcherny, July 8 2026
• Community — the system-prompt-stripping discourse the same week: @mattpocockuk · @bentossell
• Related guides: Stop Claude Code From Over-Engineering · Claude Code Effort Levels · MCP Context Bloat Fix · CLAUDE.md vs AGENTS.md vs Skills
• Client reference: /clients/claude-code