vault: session notes 2026-07-16

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

@@ -0,0 +1,30 @@
+---
+summary: "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."
+tags:
+  - type/reference
+  - tool/claude-code
+  - domain/plugins
+scope: global
+date: 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.