Playbook · 12 min read

Cleanup your Claude Code in 45 minutes

The 8-phase audit that recovers 5 hours a month, cuts startup from 8 seconds to 2, and stops bleeding $75–$375 a month at API tier on plugins you forgot you installed.

This walkthrough is adapted from Naqeeb Ali-Shamsi's When Your AI Assistant Becomes a Junk Drawer (March 2026). The numbers below are his, measured on his own setup before and after.

The damage report

Three numbers worth internalizing before you start clicking:

The ownership rule

Before any of the phases, internalize the one rule that drives every decision:

Every capability in your setup gets exactly one owner.

Map every tool — plugin, MCP, skill, hook, slash command — to the capability it owns: "run tests", "query our prod database", "review PRs". If two tools own the same job, one of them is leaving. No exceptions.

Phase A — Backup everything

Do not skip this. Cleanup involves rm. Make a complete copy first.

cp -a ~/.claude ~/.claude.backup.$(date +%Y%m%d)
# on Windows PowerShell:
# Copy-Item -Recurse $env:USERPROFILE\.claude $env:USERPROFILE\.claude.backup.$(Get-Date -Format yyyyMMdd)

Phase B — Health check

Run the diagnostics that come with Claude Code. Capture the output — you will want it to compare against later.

/doctor    # surfaces config, MCP, and hook health
/memory    # what is in CLAUDE.md (global + project)
/mcp       # which MCPs are registered + their scope
/config    # settings.json snapshot

Phase C — Normalize memory

The global ~/.claude/CLAUDE.mdis read on every session start. If it has project-specific rules, you are paying tokens to load irrelevant context every time. Move project-specific instructions to the project's own CLAUDE.md. Keep the global file for things that genuinely apply everywhere — your preferred language, your name, the model you default to.

Phase D — Normalize settings + plugins

Disabled-but-installed plugins still contribute to startup overhead. The fix is to uninstall, not disable.

# List everything you have registered:
claude plugins list

# Actually remove what you don't use:
claude plugins remove <name>

# Naqeeb went from 49 to 3.

Phase E — Normalize hooks

Hooks run on every tool call. An "ornamental" hook (one you added once to print a banner, then forgot) is a tax on every action. Delete hooks that do not enforce a rule or block a real failure mode.

Keep: anything that protects secrets, blocks .envwrites, validates schemas, or stops Claude from touching production. Delete: logging, banners, "just in case" checks.

Phase F — Normalize MCP scope

User-scope MCPs load for every project. Project-scope MCPs only load inside that project. If you registered githubglobally because one project uses it, that MCP's tool definitions are eating context in every other Claude session you ever start.

Audit with /mcp. For every user-scope MCP, ask: do I want this in every Claude Code session? If not, move it to project scope.

# Remove user-scope:
claude mcp remove <name> --scope user

# Add it project-scope inside the project:
claude mcp add <name> --scope project

Phase G — Sort everything else

Slash commands, snippets, custom skills, agents. Touch every one and label it:

• KEEP — used in the last 30 days, owns a clear capability.
• DISABLE — useful but not now (move to a backup folder).
• UNINSTALL — duplicate, broken, or you cannot remember what it does.
• MERGE — overlaps with another tool; consolidate into one.
• ARCHIVE — historical reference only (move to ~/.claude/archive/).

Phase H — Verify with a real project

Open a project you work in often and run a normal session. Does everything you actually use still work? If yes, you are done. If not, restore from the Phase A backup and rerun the audit on the broken piece only.

Bonus: path-scoped Skills

Once you have done the cleanup, prevent the next round of bloat with path-scoped frontmatter on every Skill. The skill only loads when Claude is touching matching files.

---
name: rsc-defaults
description: Use React Server Components by default for new files.
paths:
  - "src/frontend/**"
  - "*.tsx"
---

# RSC defaults

For files under src/frontend/, prefer Server Components.
Only opt into "use client" if the component uses hooks, browser
APIs, or interactive state.

Ship the SOP as a Skill

We package the whole 8-phase playbook as a slash-command Skill. Drop it into ~/.claude/skills/cleanup-claude-code/ and invoke it whenever your startup starts feeling sluggish. It walks the audit interactively, marks every item KEEP/DISABLE/UNINSTALL, and writes the diff for you.

Related

• Skill design principles — once you have pruned, write the next ones right.
• Five-tool carpentry — half the bloat is using MCPs where Skills would be lighter.

References

• Naqeeb Ali-Shamsi, When Your AI Assistant Becomes a Junk Drawer, Medium, March 2026. medium.com/@naqeeb-ali-shamsi
• Claude Code issue #29971 — MCP skill injection waste (~25K tokens per call).
• Vercel evaluation of skill invocation rates, cited in Naqeeb's piece — 56% never invoked.