A teammate pushed fixes to your Claude Code plugin, but `claude plugin update` says it is already at the latest version. Why?
answer
- updates compare a computed version
- plugin.json version wins first
- unchanged string, no new copy
- auto-update off for third-party catalogs
- running session keeps loaded version
basics
~20 sClaude Code updates a plugin only when its computed version changes, and a version in plugin.json comes first. A pinned "version": "1.0.0" that was never bumped keeps everyone on the cached copy, however many commits land.
solid answer
~40 sClaude Code decides whether to update by computing a version and comparing it with the one in `installed_plugins.json`. The `version` in the plugin's `plugin.json` comes first, then the marketplace entry's `version`, and only when neither is set does it fall back to the source, such as the commit SHA shortened to 12 characters. So a manifest pinned at `1.0.0` stays at `1.0.0` across any number of commits, and `claude plugin update` prints `already at the latest version`. The fix is to bump `version` on every release, or to omit it from both files so users track commits. Two more reasons fixes do not show up: background auto-update is off by default for third-party marketplaces, and a running session keeps the version it loaded until `/reload-plugins` or a restart.
code
bash · 5 linesclaude plugin update team-toolkit@platform-tools
# team-toolkit is already at the latest version (1.4.0).
grep '"version"' plugins/team-toolkit/.claude-plugin/plugin.json
# "version": "1.4.0" <- unchanged across the new commits
claude plugin validate ./platform-toolsgo deeper
Recall that a plugin updates only when its version changes, and that a version pinned in plugin.json must be bumped for users to get a fix.
Explain the resolution order (plugin.json, then marketplace entry, then source SHA or digest) and why setting version in both places is a defect.
Diagnose a stale plugin end to end: the computed version, auto-update defaults per marketplace, sessions and processes holding the old path, and in-place loading that hides the problem from authors.
Choose a release model for a team catalog: explicit semver bumps versus commit tracking, refs or SHAs for holding users back, and whether auto-update is on.
## How Claude Code decides a plugin changed Every installed plugin has a **computed version**. It names the plugin's cache directory, `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`, and it is what `claude plugin update` and background auto-update compare to decide whether anything changed. When the newly computed version equals the one recorded in `installed_plugins.json`, Claude Code does not replace the cached copy and prints `<name> is already at the latest version (<version>).` ## The resolution order For a marketplace added by source, and any plugin source type except `command`: 1. The `version` field in the plugin's `plugin.json`. 2. The `version` field in the plugin's marketplace entry. 3. Neither set: a value derived from the source. | Source type | Version when no `version` field is set | |---|---| | `github`, `url`, `git-subdir` | The source commit SHA, shortened to 12 characters | | `archive` | The SHA-256 digest, shortened to 12 characters | | Relative path in a git-hosted marketplace | The commit SHA of the installed directory | | Local directory outside git, or `npm` | `unknown` | The trap follows directly: a manifest with `"version": "1.0.0"` keeps every user on the cached copy until the author changes that string, **however many commits are pushed**. ## Choosing a release policy - **Bump `version` on each release.** Users get exactly the releases you cut, nothing in between. Forgetting the bump means nobody receives the fix. - **Omit `version`** from both `plugin.json` and the marketplace entry. Users track commits, since each commit changes the SHA-derived version. - **Never set it in both places.** The `plugin.json` value wins without a warning at load, and `claude plugin validate` reports the mismatch as `Entry declares version "<a>" but <path>/plugin.json says "<b>"`. To hold users on a release deliberately, a catalog owner points the entry at a `ref` or `sha`, or users add the marketplace with `#<ref>` for a branch or tag. ## Other reasons a fix does not arrive 1. **Auto-update is off.** It is on by default for most of Anthropic's official marketplaces and for marketplaces added from claude.ai, and off for community, third-party and local development marketplaces. Without it, users get changes only when they run `claude plugin update <plugin>@<marketplace>` or use **Update now** in `/plugin`. Running `claude plugin marketplace update` with no name refreshes catalog listings but leaves installed plugins where they are. 2. **The session still has the old copy.** Updates write to disk; the running session keeps what it loaded. After a background update you see `Plugin updated: <name> · Run /reload-plugins to apply`, and the next launch loads the new version anyway. 3. **Processes keep the old path.** When a copied plugin updates mid-session, its hook commands and MCP and LSP servers keep using the previous version's directory until `/reload-plugins`; monitors need a restart. 4. **The fix lives outside the plugin directory.** Installed plugins are copied into the cache, and files above the plugin root, such as `../shared`, are not copied. ## When version does not matter A plugin loaded **in place** ignores the version string: a `--plugin-dir` copy, a skills-directory plugin, or a relative-path plugin from a marketplace you added from a local path. Its current files load at every session start or `/reload-plugins`. That is why a plugin author sees fixes immediately while users on the hosted marketplace do not. ## A worked example A team ships `team-toolkit` from its `platform-tools` marketplace with `"version": "1.4.0"` in `plugin.json`. Over a week three fixes are merged, but nobody touches the version string. Each user's computed version is still `1.4.0`, so background auto-update (if on) and `claude plugin update team-toolkit@platform-tools` both find nothing new, and the cache keeps `.../team-toolkit/1.4.0/`. The author, meanwhile, added the marketplace from a local checkout, so the plugin loads in place and every fix appears at once on their machine. The fix is to release `1.4.1`: users with auto-update on receive it in the background after their next session starts, and everyone else runs `claude plugin update`. ## Debugging checklist - Read the cached directory name under `~/.claude/plugins/cache/` and compare it with the version you expect. - Check whether the manifest pins `version`, and whether the release bumped it. - Check the marketplace's auto-update toggle on the `/plugin` **Marketplaces** tab. - Run `/reload-plugins` or restart after the update lands.
- Should a team plugin set version at all?Set it when you want explicit releases: users get exactly the versions you cut, and you must bump it every time. Omit it from both `plugin.json` and the marketplace entry when users should track commits, since the version then derives from the commit SHA. Never set it in both places, because `plugin.json` wins silently and `claude plugin validate` reports the mismatch.
- The update landed on disk, but the session still runs the old hook. Why?A running session keeps the plugin version it loaded, and after a mid-session update its hooks, MCP servers and LSP servers keep the previous version's path. Run `/reload-plugins` to switch them, or start a new session; monitors need a restart. The previous version's directory is kept for 14 days so running sessions do not break.
- Every new commit to the plugin repository reaches users automatically.
- The marketplace entry's version overrides the one in plugin.json.
- Auto-update is on by default for every marketplace you add.
- claude plugin marketplace update with no name also updates installed plugins.
- A background update takes effect in the running session immediately.