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. Installed mods (brewmod-plan-effort, brewmod-placeholders) are checked and updated too, never installed; a mod that is not installed gets no row and never shows ❌.

Quick reference

FieldValue
Command/brewtools:plugin-update
Arguments[prompt] [check|update|all] — free-form prompt first; 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 (versions are placeholders):

PluginInstalledLatestStatus
brewcodeX.Y.0X.Y.1⬇️ update available
brewdocX.Y.1X.Y.1✅ current
brewtools—X.Y.1❌ missing
brewuiX.Y.1X.Y.1✅ current
brewmod-placeholdersX.Y.0X.Y.1⬇️ update available

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, projectPath (present only on project/local rows, absent on user rows), 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 settings.json in the config directory (CLAUDE_CONFIG_DIR, default ~/.claude) and walks the plugin cache (CLAUDE_CODE_PLUGIN_CACHE_DIR, default <config dir>/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 stays read-only: the failure is reported and nothing is inferred as missing or outdated.

  3. Render status table

    Prints the version table for all four suite plugins (brewcode, brewdoc, brewtools, brewui), each installed mod (brewmod-plan-effort, brewmod-placeholders), 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). Mods are never offered or installed here, even when named in the prompt; the summary prints their claude plugin install command for you to run. 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”; installed mods are updated in both “Update all” and “Update suite only”) — 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 always passed, because CLIs before 2.1.281 read an omitted scope as user and would update the wrong instance. Project and local rows resolve from the working directory, so each runs as (cd "<projectPath>" && claude plugin update <id> --scope <scope>) and the session directory stays untouched; a missing projectPath is reported as an orphan install with its uninstall command and nothing is run. 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. Auto-update is OFF by default for a third-party marketplace like claude-brewcode, and the only switch is the /plugin UI (Marketplaces → claude-brewcode → Enable auto-update); no CLI sets it. The skill never patches settings.json directly and only points you to the UI.

  7. Prune orphaned dependencies

    Interactive and all only; check and update skip it. 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 (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 without a TTY removes nothing and still exits 0, so the run would look pruned when it was not. Non-fatal if the CLI lacks prune — prints a skip notice and continues.

  8. Reload notice + final summary

    Always printed at the end of every run (check included), 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, projectPath (project/local rows) 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 settings.json in the config directory (CLAUDE_CONFIG_DIR, default ~/.claude) for marketplace registrations and walks the plugin cache (CLAUDE_CODE_PLUGIN_CACHE_DIR, default <config dir>/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>      # user/managed rows, repeat per selected plugin
(cd "<projectPath>" && claude plugin update <id> --scope <scope>)   # project/local rows

Full-suite example, all four at user scope (an installed mod follows the same pattern, for example brewmod-placeholders@claude-brewcode):

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. Project and local installs also need their own projectPath as the working directory; a row whose directory no longer exists is reported as an orphan install, with mkdir -p "<projectPath>" && cd "<projectPath>" && claude plugin uninstall <id> --scope <scope> as the removal command.

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 orphaned dependencies. check stops before any of them. update auto-resolves update (“Update all”) without asking and skips both the auto-update step and the prune phase. all auto-installs, auto-updates everything, and auto-picks “Prune listed”; it asks nothing, and the auto-update step only prints the /plugin UI hint.

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.

🧩

Brewcode mods

Optional add-ons this skill keeps current.

Updating plugins

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