Claude Code /checkup: Let AI Diagnose and Clean Up Configuration Debt¶
For / Key Points
For: Engineers who use Claude Code daily and teams that manage Claude Code skills, MCP servers, plugins, hooks, and CLAUDE.md files.
Key Points:
- Claude Code v2.1.205 changed
/doctorinto a setup checkup that can diagnose and fix issues, with/checkupas an alias - The seven suggestions cover unused skills, MCP servers, plugins, CLAUDE.md duplication, nested instructions, slow hooks, updates, and permissions
- Enabling auto mode by default and pre-approving read-only commands should be treated as permission-policy changes, not simple cleanup
The longer you use Claude Code, the more your helpful configuration can become weight. You add skills, connect MCP servers, write hooks, and keep appending exceptions to CLAUDE.md.
Eventually, Claude Code starts each session with more to read, more to choose from, and more to wait for. This article asks how to treat /checkup not merely as a cleanup command, but as a maintenance loop for AI-agent configuration.
What Changed¶
Claude Code v2.1.205, released on July 8, 2026, changed /doctor into a full setup checkup that can diagnose and fix issues. The same release added /checkup as its alias1.
Before this change, /doctor was mainly a diagnostic entry point. The official troubleshooting docs describe it as a way to check installation health, settings validity, MCP configuration, and context usage in one pass2. The new behavior moves it from status reporting into cleanup and optimization.
Claude Code developer Boris Cherny listed seven actions that /checkup can suggest3. He also stated that it confirms with the user before making changes3. The GitHub release notes confirm the /doctor redesign and /checkup alias, but not the full seven-item breakdown. Treat the list below as based on the developer announcement, and treat the actual /checkup screen as the source of truth in production.
The Seven Suggestions¶
The seven items make more sense when separated into cleanup work and permission-policy changes.
| # | Suggestion | Purpose |
|---|---|---|
| 1 | Remove unused skills, MCP servers, and plugins | Reduce always-present descriptions and tool metadata |
| 2 | Deduplicate local CLAUDE.md against checked-in CLAUDE.md | Reduce duplicate or conflicting instructions |
| 3 | Break root CLAUDE.md into nested CLAUDE.md files and skills | Move always-on context to on-demand context |
| 4 | Turn off slow hooks | Reduce event-level waiting time |
| 5 | Update Claude Code | Pick up fixes and improvements |
| 6 | Enable auto mode by default | Reduce approval prompts |
| 7 | Pre-approve frequently denied read-only commands | Reduce approval waits |
Items 1 through 5 are mostly environment maintenance. Items 6 and 7 can improve flow, but they also change the permission boundary. They should not receive the same review treatment.
Why Cleanup Matters¶
Unused extensions remain part of the decision surface even when you are not actively using them. The Claude Code docs explain that CLAUDE.md content loads at session start, and skill descriptions load at session start by default so Claude can decide when to use them4. For MCP servers, full schemas are deferred until use, but connected tool names load at session start4.
The costs are not identical. Still, the more configuration you add, the more choices Claude carries from the beginning of the session.
Add a tool
→ add descriptions, tool names, and settings
→ expand effective context and decision surface
→ increase compaction and mis-selection risk
→ reduce stability on long tasks
Root CLAUDE.md files create a similar problem. Project-wide instructions are useful, but once they grow large, they become a fixed cost for every session. The Claude Code docs recommend keeping CLAUDE.md short and moving reference material to skills that load on demand4.
Nested CLAUDE.md files and .claude/rules/ can load only when Claude works with matching files or directories5. That makes suggestion 3 more than deletion. It moves configuration from fixed cost to variable cost.
Slow Hooks Hit the User Experience¶
A slow hook may look harmless if it only costs a few seconds once. The problem is cadence.
Claude Code hooks can fire at session start, prompt submission, tool calls, compaction, and other lifecycle points6. Hooks such as UserPromptSubmit run before model processing, so a stuck or slow hook stalls the session6.
That is why "turn off slow hooks" belongs in a setup checkup. When Claude Code feels slow, the model may not be the bottleneck. The surrounding automation may be.
/doctor Was Already Becoming the Diagnostic Hub¶
This was not an isolated addition. Recent releases show a steady move toward concentrating startup warnings and diagnostics in /doctor1.
| Version | Release Date | Change |
|---|---|---|
| v2.1.178 | June 15, 2026 | Improved /doctor with a consistent flat-tree layout across sections |
| v2.1.183 | June 19, 2026 | Removed the startup "setup issues" line and directed configuration issues to /doctor |
| v2.1.203 | July 7, 2026 | Moved startup "claude command missing or broken" warnings to /doctor and /status |
| v2.1.205 | July 8, 2026 | Made /doctor a diagnose-and-fix setup checkup and added /checkup as an alias |
Instead of printing warnings on every startup, Claude Code is moving them into one intentional maintenance entry point. /checkup is the visible endpoint of that design direction.
Treat Permission Relaxation Separately¶
Suggestions 6 and 7 are not just cleanup. They change the permission posture.
Enabling auto mode by default reduces approval prompts. Pre-approving read-only commands expands what Claude can do without waiting for a human decision.
For solo development, that may be exactly the right tradeoff. For managed environments, it should be checked against existing policy before adoption.
A practical split is:
- Usually easy to apply: inventory unused skills, MCP servers, plugins, and old Claude Code versions
- Requires diff review: deduplicate CLAUDE.md, split root instructions, and convert material into skills
- Requires policy review: enable auto mode by default and pre-approve read-only commands
Because /checkup asks item by item, teams can apply the cleanup items and decline the permission-relaxing items.
From Manual Cleanup to a Maintenance Loop¶
Claude Code cleanup existed before /checkup. In a March 31, 2026 Medium post, Naqeeb ali Shamsi described a manual process for auditing unused plugins, user-scoped MCP servers, oversized CLAUDE.md files, and stale hooks7.
The enduring lesson is not "never add configuration." It is that every added capability needs an owner, a purpose, and a removal condition.
/checkup brings that inventory loop into the product. Just as Dependabot detects aging dependency state, Claude Code is starting to detect aging agent configuration. That is not just a small UI improvement. It is a sign that AI-agent operations are maturing.
Summary¶
/doctor is now more than diagnostics, and /checkup is its alias. Of the seven suggested actions, five are configuration-debt cleanup and two are permission changes. They appear in one flow, but they deserve different review standards.
The next question is cadence. Should this stay as an occasional manual check, or become part of regular configuration reviews, team onboarding, or pre-release checks?
Skills, MCP servers, CLAUDE.md, and hooks are all best on the day they are written. After that, the surrounding environment changes. AI-agent configuration now needs the same kind of maintenance loop as code. /checkup is the entry point.
Related Articles¶
- What Is Harness Engineering? What Do You Actually Build?
- What Are Claude Code Dynamic Workflows?
- What Is Loop Engineering?
anthropics/claude-code Releases. See v2.1.178, v2.1.183, v2.1.203, and v2.1.205. ↩↩
Boris Cherny, "New in Claude Code: /checkup", X, July 8, 2026. ↩↩
Claude Code Docs, "Extend Claude Code", "Understand context costs". ↩↩↩
Naqeeb ali Shamsi, "When Your AI Assistant Becomes a Junk Drawer", Medium, March 31, 2026. ↩