plugin-update — manage plugin versions

Caution

Running old plugin versions causes silent mismatches. Skills added in newer releases are missing. Fixes don’t apply. The skill manifest Claude loads at startup can be weeks behind the repo. There is no auto-update prompt — you have to ask.

Tip

One skill checks, installs, and updates the full brewcode suite. Interactive by default — or pass check / update / all to skip questions.

Quick reference

FieldValue
Command/brewtools:plugin-update
Arguments[check|update|all] — no args = interactive
Modelsonnet
Contextsession
ToolsRead, Bash, Write, AskUserQuestion, WebFetch

When to use

  • Version check before a long session — confirm the suite is current before investing time
  • After seeing unfamiliar errors — an outdated plugin may lack a fix already released
  • First run on a new machine — install all four plugins non-interactively with all
  • CI / scripted setup — all mode skips every confirmation prompt
SituationCommand
Just check versions, change nothing/brewtools:plugin-update check
Update what’s outdated, skip missing/brewtools:plugin-update update
Install missing + update all, no prompts/brewtools:plugin-update all
Walk through each decision interactively/brewtools:plugin-update

Examples

# Interactive — check versions and decide what to update
/brewtools:plugin-update

# Status check only — no changes made
/brewtools:plugin-update check
# Update all outdated plugins non-interactively
/brewtools:plugin-update update

# Install missing + update all — fully non-interactive
/brewtools:plugin-update all

After a run you will see a version table like this:

PluginInstalledLatestStatus
brewcode3.4.513.4.52⬇️ update available
brewdoc3.4.513.4.51✅ current
brewtools—3.4.51❌ missing
brewui3.4.513.4.51✅ current

Status legend: ✅ current · ⬇️ update available · ❌ missing · ❓ unknown.

Flow

  1. Discover installed plugins

    Primary path: runs claude plugin list —json (CC 2.1.163+, prefixed with unset CLAUDECODE && inside a session). Returns an array of objects: id, version, scope, enabled, installPath, installedAt, lastUpdated, and optional mcpServers. The version field may read “unknown” for locally-loaded plugins. Fallback: if the command errors, returns empty output, or produces invalid JSON, the skill runs discover-plugins.sh, which reads ~/.claude/settings.json and walks ~/.claude/plugins/cache/ directly.

  2. Fetch latest versions

    Fetches release metadata from GitHub. If the network request fails, all latest versions are marked “unknown” and the run continues — you can still update without knowing the exact latest tag.

  3. Render status table

    Prints the version table for all four suite plugins (brewcode, brewdoc, brewtools, brewui) plus any other installed plugins as informational rows. Argument check stops here — no changes are made.

  4. Install missing plugins

    For each suite plugin not present: asks whether to install (interactive) or auto-installs (all mode). Runs claude plugin marketplace add first (idempotent), then per-plugin install. Skipped entirely for the update argument.

  5. Update outdated plugins

    Asks which plugins to update (“Update all” incl. non-suite plugins / “Update suite only” / “Update selected” / “Skip”) — update and all auto-pick “Update all” without asking. The update set is built from that answer, never from a fixed list. Runs a marketplace refresh once, then one claude plugin update <id> —scope <scope> per selected plugin, using each plugin’s own installed scope from discovery. —scope is mandatory here — it defaults to user, so a plugin installed at project/local/managed scope would otherwise update the wrong instance. Shows full CLI output for every command; any single failure is reported and the run continues.

  6. Auto-update toggle hint

    Only in interactive and all modes. Explains how to enable per-marketplace auto-update via the /plugin UI (Marketplaces → claude-brewcode). The skill never patches settings.json directly — the exact key is unverified.

  7. Prune stale plugin caches

    Skipped entirely for check (which stops after the status table). Otherwise previews orphaned auto-installed dependencies with claude plugin prune —dry-run —scope <scope>, once per distinct scope seen during discovery — plugins installed directly are never touched. Empty preview → nothing to remove. Non-empty preview asks once on the exact list, except update mode auto-resolves it to “Skip” (preview shown, nothing removed) and all auto-picks “Prune listed”; on a “Prune listed” answer it runs claude plugin prune —scope <scope> -y. The -y flag is mandatory: the Bash tool is not a TTY, and a bare prune hangs on its confirmation prompt. Non-fatal if the CLI lacks prune — prints a skip notice and continues.

  8. Reload notice + final summary

    Always printed, even on no-op runs. Lists what was installed, updated, skipped, and any errors. Preferred reload: run /reload-plugins in this session. Fallback: exit, then claude again.

Warning

Run /reload-plugins or restart the session after any install or update. Claude Code reads skill and agent definitions once at startup — changes take effect only after a reload.

Internals

Discovery — primary: claude plugin list --json (available since CC 2.1.163). Returns objects with fields id, version, scope, enabled, installPath, installedAt, lastUpdated, and optionally mcpServers. The version field may be "unknown" for dev-mode plugins. When run inside a session, the Bash invocation is prefixed with unset CLAUDECODE && to avoid the env-var conflict. Fallback: if the command errors, returns empty output, or returns invalid JSON (CC older than 2.1.163), the skill falls back to discover-plugins.sh, which parses &#126;/.claude/settings.json for marketplace registrations and walks &#126;/.claude/plugins/cache/ for installed version directories.

Update chain — marketplace refresh once, then one command per plugin actually selected, --scope mandatory and taken from that plugin’s own discovery row:

claude plugin marketplace update claude-brewcode
claude plugin update <id> --scope <scope>      # repeat per selected plugin

Full-suite example, all four at user scope:

claude plugin update brewcode@claude-brewcode --scope user
claude plugin update brewdoc@claude-brewcode --scope user
claude plugin update brewtools@claude-brewcode --scope user
claude plugin update brewui@claude-brewcode --scope user

Each command runs via the Bash tool with full output shown. Failures are reported inline; remaining steps continue regardless. Omitting --scope silently updates the user-scoped instance even when the installed one is project/local/managed — this is why the skill always passes it explicitly.

No delegation — this skill spawns nothing. Task is deliberately absent from its allowed-tools: discovery, the update chain, and the gates all run in the main conversation, where you can see every command and its output.

Interactive gates — AskUserQuestion presents option lists only (no free-text). Four decision points: install missing, update outdated, enable auto-update, prune stale caches. check stops before any of them. update auto-resolves update (“Update all”) and prune (“Skip”, preview shown but nothing removed) without asking, and skips the auto-update step entirely. all auto-installs, auto-updates everything, and auto-picks “Prune listed” — only the auto-update toggle still runs its own question in all mode.

Claude refuses to execute? — if Claude summarizes instead of running commands, paste this coercive prompt: “Execute every claude plugin ... command shown above using the Bash tool. Do not describe — run each command and show full output.”

🔗

GitHub source

Source code, discovery scripts, and update references.

📄

Brewtools overview

All brewtools skills in one place.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.