SecondBrain/reference/claude-code-plugin-cache-is-version-gated.md

summary	tags	scope	date
Claude Code caches installed plugin source per version; `claude plugin update` only refreshes when plugin.json's version changes — editing source without a version bump leaves every install serving stale files.	type/reference tool/claude-code domain/plugins	global	2026-07-16

Claude Code plugin cache is version-gated

Installed plugins are cached at ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/. Editing a plugin's source in its marketplace repo does NOT propagate to installs: claude plugin update <plugin>@<marketplace> reports "already at the latest version" and skips the copy unless plugin.json's version field changed.

Workflow after editing an installed plugin's source:

1. Bump version in .claude-plugin/plugin.json (commit it).
2. claude plugin update <plugin>@<marketplace> — copies source into a new <version>/ cache dir.
3. Restart the session to apply.

Also: there is no claude refresh-plugins subcommand — running it hangs (the CLI treats the unknown token as an interactive prompt). The real subcommand set lives under claude plugin (install, update, enable, disable, list, validate, tag, ...).

Discovered 2026-07-16 when cc-architect doc fixes didn't appear in the global install's cache until the version was bumped 1.0.0 → 1.0.1.