Claude Code plugin update: how to make your plugins update themselves

TL;DR Third-party marketplaces and local directory ones ship with auto-update off by default; only the official one and the ones from claude.ai ship with it on. Add "autoUpdate": true to that marketplace's extraKnownMarketplaces entry and Claude Code refreshes it in the background. And when claude plugin update answers already at the latest version while you keep seeing old code, the cache isn't misbehaving: it compares the version string, so bump version in plugin.json.

You install a plugin, yours or somebody else's, and weeks later it is exactly what it was on install day. No notification, no hint. And when you finally get suspicious and run the update command, it tells you that you are current.

This isn't a bug. It is two separate behaviours overlapping, documented in two different places.

Look at it on your own machine first

Claude Code keeps the marketplaces it knows in ~/.claude/plugins/known_marketplaces.json, each with the date of its last refresh. Here is mine, untouched:

claude-plugins-official   Sep 21     (auto-update on by default)
craft                     Sep 22     "autoUpdate": true
ai-plugins                Jul 8
claude-code-warp          May 25
chrome-devtools-plugins   May 8
juanwmedia-cc-tips        May 2
seo-workflow              Apr 29

The top two refresh themselves. The five below have been frozen for two to five months. Not my network, not my version, not the desktop app: that is the default.

The sentence is in the docs and slips past everyone because it lands at the end of a long section: claude-plugins-official, most other official Anthropic marketplaces and the ones you add from claude.ai have auto-update enabled. Everything else, your own marketplace included, has it disabled.

The fix is one line per marketplace

In ~/.claude/settings.json, next to that entry's source:

{
  "extraKnownMarketplaces": {
    "craft": {
      "source": {
        "source": "github",
        "repo": "juanwmedia/craft"
      },
      "autoUpdate": true
    }
  }
}

That is the whole change. From your next session on, Claude Code refreshes that marketplace and updates its installed plugins in the background.

You can do the same by hand in /plugin, Marketplaces tab, pick the marketplace and choose Enable auto-update. Same lever, different handle, and it comes with a catch you will meet further down.

Three things worth knowing before the behaviour surprises you:

• The refresh doesn't happen at startup, it happens after startup, with a random delay of up to ten minutes. That is deliberate: your open session keeps running the versions it loaded at launch.
• If anything did update, you get a prompt to run /reload-plugins. Ignore it and the new versions load on your next launch.
• If you set DISABLE_AUTOUPDATER to freeze Claude Code, you freeze your plugins along with it. To split the two, FORCE_AUTOUPDATE_PLUGINS=1, which is exactly the side effect the auto update failed tip covers.

Now the second bite: the version string decides

This is the one that drives anybody maintaining their own plugin up the wall. My ai-infra marketplace points at a local directory, my own repo. I run the update command:

$ claude plugin update ai-infra@ai-infra
Checking for updates for plugin "ai-infra@ai-infra" at user scope…
✔ ai-infra is already at the latest version (1.1.8).

It isn't. The copy this session loads lives in ~/.claude/plugins/cache/ai-infra/ai-infra/1.1.8 and sits two commits behind my repo: board.json, manifest.json and four files under examples/ all differ. A diff -rq between the two folders says so line by line.

The reason is plain once you see it: what gets compared is the version string in plugin.json, not the content. I had edited the repo without touching version, so as far as Claude Code was concerned there was nothing to update. That is why the cache looks well behaved some days and possessed on others. It isn't the cache, it is whether you bumped the number.

Bump it and everything lines up:

{ "name": "ai-infra", "version": "1.1.9" }

✔ Plugin "ai-infra" updated from 1.1.8 to 1.1.9 for scope user. Restart to apply changes.

Every version installs into its own folder inside the cache, so developing one bump at a time leaves a stack of directories in there. Thirteen, in my case. I deleted three of the old ones and the plugin kept loading the current one without complaining; the one you leave alone is the version in use.

If what you actually want is to see your changes without publishing or bumping anything, don't come this way: that is the job of --plugin-dir, which overrides the installed plugin for that session. Auto-update is for what you already shipped and other people run.

If you work in Claude Code Desktop

This is the part that misleads people, because it looks like an app bug and isn't one. The /plugin panel belongs to the terminal. In Desktop you get a plugin browser (the + next to the prompt box, then Plugins), and there you can install, enable, disable and uninstall, but there is no auto-update toggle.

So the interface path simply doesn't exist in Desktop, which is why it feels like "it updates in the CLI and not here". It was updating in neither. What changes is that the terminal hands you the lever.

In Desktop the fix is the same one above, editing settings.json, which is also the one that survives moving machines. To force something by hand at any point, from your shell:

claude plugin marketplace update <marketplace>
claude plugin update <plugin>@<marketplace>

Then /reload-plugins inside the session. It works in Desktop from v2.1.260, with two conditions: you have to type it yourself into the prompt box (sent over Remote Control it declines), and it does not reconnect the plugin's MCP servers, which wait for your next session.

Reference

And before you ship any new version, claude plugin validate catches what breaks the plugin and claude plugin eval tells you whether it contributes anything at all. If the plugin doesn't exist yet, the marketplace is the step before this one.

Official docs: Discover and install prebuilt plugins

Requirements

• Everything above was run on v2.1.278.
• /reload-plugins in Desktop or in non-interactive mode needs v2.1.260 or later.
• The absence of an auto-update toggle in the Desktop plugin browser is what Anthropic documents; I could not capture it on screen.