plugin-doctor

Fix disabled Claude Code plugins that keep firing anyway.

The Problem

When you disable a plugin in Claude Code's /plugin UI, the toggle flips to "disabled" — but the plugin's skills still show up in autocomplete and still execute when invoked. /simplify will fire even though code-simplifier is disabled.

This happens because Claude Code's plugin system has three independent layers that don't stay in sync:

Layer	File	What happens on disable
Settings	~/.claude/settings.json	enabledPlugins[id] set to false
Ledger	~/.claude/plugins/installed_plugins.json	Entry stays. Nothing changes.
Cache	~/.claude/plugins/cache/{marketplace}/{plugin}/	Files stay on disk. Skills still load from here.

The skill resolver reads from cache. It doesn't check the settings flag. So "disabled" is cosmetic.

Worse: if you manually delete the cache, /reload-plugins re-downloads it because the ledger and settings entries still exist. You have to purge all three layers or it comes right back.

What plugin-doctor does

Scans all three layers, finds the disagreements, and deletes everything for disabled plugins in one shot:

1. Deletes the cache directory (stops skills from loading)
2. Removes the ledger entry (stops re-download on reload)
3. Removes the enabledPlugins entry (stops it showing in the Installed tab)

Also finds orphan caches — directories in plugins/cache/ that have no corresponding settings entry at all.

Usage

# See what's broken (no changes made)
bash plugin-doctor.sh

# Preview what would be deleted
bash plugin-doctor.sh --dry-run

# Fix it — purge all disabled plugin artifacts
bash plugin-doctor.sh --fix

After --fix, run /reload-plugins in Claude Code to apply.

Install as a skill

Copy to your Claude Code skills directory to get /plugin-doctor in autocomplete:

mkdir -p ~/.claude/skills/plugin-doctor
cp plugin-doctor.sh ~/.claude/skills/plugin-doctor/
cp SKILL.md ~/.claude/skills/plugin-doctor/

Or with npx (if published to skills.sh):

npx skills add adairlabs/plugin-doctor

Example output

Plugin Doctor — Claude Code plugin layer audit
────────────────────────────────────────────────

  ● Enabled plugins:  9
  ● Disabled plugins: 75

Zombie Scan (disabled in settings, cache still on disk)

  ✗ code-simplifier@claude-plugins-official
    Cache: ~/.claude/plugins/cache/.../code-simplifier/1.0.0 (20K)
    ⚠ 1 skill/agent file(s) still loadable
  ✗ engineering-skills@claude-code-skills
    Cache: ~/.claude/plugins/cache/.../engineering-skills/2.1.2 (5.0M)
    ⚠ 50 skill/agent file(s) still loadable
  ...

Orphan Scan (cache dirs with no settings.json entry)

  ? postman@claude-plugins-official (283M)
  ? imessage@claude-plugins-official (29M)
  ? claude-mem@thedotmack (250M)
  ...

Summary
  Zombies:        74
  Ledger-only:    0
  Orphan caches:  25

How we found this

Disabled code-simplifier in the plugin UI. Ran /simplify. It fired anyway. Dug into each layer:

• settings.json correctly said false
• Plugin UI correctly showed "disabled"
• /reload-plugins dropped the plugin count from 10 to 9
• But the skill count stayed at 12 — unchanged
• /simplify still appeared in autocomplete
• The cache directory still had the agent .md file on disk
• Deleting just the cache didn't work — /reload-plugins re-downloaded it
• Had to purge settings + ledger + cache together to actually kill it

74 disabled plugins were in this state. 25 more were orphaned caches with no settings entry at all. Some were 250MB+.

Files

File	Purpose
plugin-doctor.sh	Diagnostic + cleanup script
SKILL.md	Claude Code skill definition (enables /plugin-doctor command)

Requirements

• jq — brew install jq
• Claude Code with the plugin system