claude-plugin-doctor

claude-plugin-doctor

Diagnose drift across the six cache layers of the Claude Code / Claude Desktop plugin system, and recommend the minimum-impact fix.

Why

A plugin author bumps a marketplace, hits Refresh, hits Update — and Claude is still loading the old skill. The reason: the plugin system has six independent cache layers, and any one of them can be stale on its own. cpd walks every layer, computes the drift, and tells you the smallest action that fixes it.

The six layers:

1. Marketplace clone (marketplaces/<mp>/)
2. Plugin install snapshot (cache/<mp>/<plugin>/<version>/)
3. Claude Cowork session mirror (per-account/org)
4. Backend remote marketplace catalog
5. Cowork in-app install — "Personal plugins" (<userData>/.../rpm/)
6. Standalone Claude Code remote SSH content-hash sync

See the Architecture & Design Gist for the full design, or run cpd explain for the in-tool cheat-sheet.

Install

CLI (always required)

npm i -g claude-plugin-doctor
# or run without installing
npx claude-plugin-doctor

Aliased binary: cpd. Requires Node 20+.

Claude Code / Cowork plugin (optional, recommended)

Installing the bundled plugin gives Claude Code and Claude Cowork agents a skill that auto-triggers on plugin-staleness symptoms (e.g. "claude plugin update says already at latest version") and drives cpd for you. The plugin requires cpd on PATH — install the CLI above first.

# Add the marketplace
claude plugin marketplace add yaniv-golan/claude-plugin-doctor

# Install the plugin
claude plugin install claude-plugin-doctor@cpd

Or, from inside a Claude Code session:

/plugin marketplace add yaniv-golan/claude-plugin-doctor
/plugin install claude-plugin-doctor@cpd

Platform support

cpd is macOS-only. Linux and Windows currently exit with E_PLATFORM_UNSUPPORTED. Linux support is on the roadmap; Windows is later.

What it looks like

A full scan summarizes drift across every discovered root and emits an ordered fix list:

$ cpd

✗ Drift detected — 2 fixes available below  (manual action required)

Topology:
  Standalone Claude Code         ~/.claude/plugins
                                 3 marketplace(s)
  Claude Cowork (active)         ~/Library/Application Support/Claude/.../<acc>/<org>
                                 2 marketplace(s)

Drift summary:
  Marketplaces      1 stale
  Plugins           3 affected (2 stale, 1 registration mismatch)
  Surfaces          1 change needs a new task or app restart to take effect

Recommended actions, in order:
  1. claude plugin marketplace update acme-marketplace
     fixes: marketplace clone behind remote (acme-marketplace)
  2. (manual)  Bump plugin.json#version in my-dev-plugin's source repo, commit, push, then refresh + update.
     For per-plugin step-by-step:
       cpd check my-dev-plugin@local-mp

After fixes:
  ⚠ Restart Claude Desktop for config changes to take effect.

Exit code: 3  (drift detected, manual action required)

For a single-plugin deep-dive:

$ cpd check transcription-reader@transcription-reader-marketplace

Plugin:        transcription-reader@transcription-reader-marketplace  (in standalone Claude Code)
Source:        https://github.com/.../transcription-reader-skill.git (git)
Installed:     0.3.0  (scope=user)
               commit  ca7cdf74bfb7
               last update  2026-05-03 (~21 hrs ago)

Fix:
  claude plugin update transcription-reader@transcription-reader-marketplace

Marketplace clone (transcription-reader-marketplace)
  ✓ fresh — Local clone matches remote HEAD (918b0ea).

Plugin install on disk
  ⚠ stale — Stale install — plugin.json has 0.4.0, you have 0.3.0
       installed       0.3.0  (commit ca7cdf7)
       plugin.json     0.4.0
       fix             claude plugin update

Other caches       not applicable here (Cowork session mirror, Cowork in-app install, remote SSH cache, backend marketplace catalogue (server-side, no local cache))