plugins: project-scope pins accumulate per worktree (15 paths x ~60 plugins, 3 paths gone, 412 cached versions)

[kyle-sexton]

Summary

~/.claude/plugins/installed_plugins.json on the laptop carries project-scope entries for 15 project paths, each pinning roughly 57 to 65 plugins at the version current when that project first enabled them. Three of those paths no longer exist on disk. The pins never update, so the plugin cache holds 412 version directories (963 MB) and the file keeps growing with every worktree that has a .claude/settings.json enabling the fleet.

Evidence (2026-09-02, Claude Code 2.1.259)

• jq over installed_plugins.json: project-scope pins per path: claude-code-plugins 65, six D:\worktrees\ccp-* paths 63-64 each, chezmoi source 63, provisioning 57, and three paths that no longer exist (chezmoi-worktrees\...-feat-cross-platform-wsl, chezmoi\.claude\worktrees\linux-lane-parity, D:\worktrees\dotfiles-statusline).
• guardrails alone: user scope 0.31.2, project pins at 0.29.9, 0.29.12 (x9), 0.30.0 (x6).
• Transcripts from sessions in the claude-code-plugins checkout reference plugins/cache/melodic-software/guardrails/0.31.1, the user-scope version at the time, so the user scope wins and the pins are not running stale hook code. They are disk and clutter only.
• The plugins reference says orphaned versions are swept about 14 days after an update or uninstall; a project-scope pin is never updated, so nothing ever orphans it.

Why it matters

Every new worktree of a repo whose project settings enable the fleet adds another ~60 pinned installs. The cache never shrinks, installed_plugins.json grows, and claude plugin list prints every pin of every path, which is what makes "which version is running here" hard to answer at a glance.

Suggested handling

1. Decide whether project settings should enable plugins at all when the user scope already does; a project enabledPlugins block that mirrors the user scope buys nothing on a single-operator fleet and is the source of every pin.
2. If they stay, add a sweep to the disk-hygiene or claude-ops audit: claude plugin uninstall <plugin> --scope project for pins whose projectPath no longer exists, and a report of pins that are more than N versions behind the user scope.
3. Consider claude plugin prune --scope project coverage in the same sweep.

Verification

jq -r '.plugins | to_entries[] | .value[] | select(.scope=="project") | .projectPath' ~/.claude/plugins/installed_plugins.json | sort -u lists the paths; test each with Test-Path.

No related issue.

[kyle-sexton]

Refreshed measurement from a /claude-ops:plugins sync run today (2026-09-04, Claude Code 2.1.260). The numbers have grown substantially since this was filed on 2026-09-03, and the "three paths no longer exist" figure is now twelve.

Current state

Read from fleet-state.sh's report on the same machine:

• installed_plugins.json is 462,371 bytes and holds 1,079 install records: 74 at user scope, 1,005 at project scope.

• 755 of those 1,005 project records (75%) point at 12 directories not present on this machine. Every one is a worktree path:

  path	records
  D:\worktrees\ccp-usage-tracking	64
  D:\worktrees\ccp-phase1b	64
  D:\worktrees\ccp-phase1d	64
  D:\worktrees\ccp-topic	64
  D:\worktrees\ccp-2c	64
  C:\Users\KyleSexton\.local\share\chezmoi-worktrees\melodic-software-dotfiles-feat-cross-platform-wsl	63
  D:\worktrees\melodic-software-provisioning-feat-cross-platform-wsl	63
  C:\Users\KyleSexton\.local\share\chezmoi\.claude\worktrees\linux-lane-parity	63
  D:\worktrees\dotfiles-statusline	63
  D:\worktrees\tmp-standards-linkage	63
  D:\worktrees\dotfiles-perf-hooks	63
  D:\worktrees\ccp-2891-gate	57

• Only 4 project paths are still present: chezmoi, claude-code-plugins, provisioning, and D:\worktrees\ccp-handoff-qol.

• Plugin cache: 436 version directories, 1.2 GB (was 412 / 963 MB when this issue was filed).

A directory test cannot distinguish a deleted worktree from an unmounted volume or an offline share, so "not present on this machine" is the accurate phrasing rather than "gone". All twelve here are known-deleted worktrees.

Downstream effect on the sync skill's own reporting

This is the part not yet captured in the issue. /claude-ops:plugins sync reported 64 actionable divergences on a fleet where nothing was actually behind: the marketplace refreshed cleanly, update-candidates-user returned 0 of 74, and missing_from_user_install and missing_from_enabled were both empty. Every one of those 64 rows was a stale project pin disagreeing with a current user scope.

Filtering each divergence's scope list down to paths that are present still leaves 61 actionable rows, because the 4 live project roots are themselves pinned behind. So the noise is not purely an artifact of the absent paths, but the absent paths are what turn a 4-repo converge job into a 64-row report.

Worked example, actionlint@melodic-software — user scope at 0.8.31, sixteen project records spread across 0.8.19 / 0.8.21 / 0.8.26 / 0.8.30, eleven of the sixteen at paths that no longer exist.

Note on the suggested sweep

Suggestion 2 in the original body proposes claude plugin uninstall <plugin> --scope project for pins whose projectPath no longer exists. That does not work as written: -s project / -s local have no path flag and always act on the current directory, so a record whose path is absent cannot be reached — there is nothing to cd into. The claude-ops:plugins skill documents this and deliberately declines to reap for exactly that reason.

That leaves three viable routes, and picking among them is the open decision:

1. Prevent at the source — have the worktree teardown path uninstall project-scope plugins while the directory still exists. This is what fix(source-control): worktree teardown leaves project-scope plugin install records forever #3113 attempted; whatever regressed there is worth re-checking against these numbers.
2. Stop creating the pins — suggestion 1 in the original body. On a single-operator fleet a project enabledPlugins block mirroring the user scope buys nothing, and it is the source of every pin.
3. Ask upstream for a prune-by-path verb. claude plugin prune acts on auto-installed dependencies and carries the same no-path-flag limitation, so no current CLI verb removes an install record by path. Editing installed_plugins.json directly is the only local option and is outside what the plugin skills will do.

Route 1 is the only one that stops the growth without hand-editing state, but it does nothing for the 755 records already stranded.

Reproduction

"$CLAUDE_PLUGIN_ROOT"/skills/plugins/scripts/fleet-state.sh > state.json
python - <<'PY'
import json, collections
d = json.load(open('state.json'))
inst = d['installed']
print('records:', len(inst), collections.Counter(i['scope'] for i in inst))
stale = [i for i in inst if i.get('projectPathPresent') is False]
print('stale:', len(stale), 'across', len({i['projectPath'] for i in stale}), 'paths')
PY

[kyle-sexton]

Triage (operator-authorized): priority: medium, work-class: structural, status: needs-decision.

Not taking this into a PR from the plugin-sync lane. It is a design decision with three routes, each outside a single claude-ops PR's blast radius:

1. Prevent at the source: uninstall project-scope plugins during worktree teardown while the directory exists. Lives in the source-control plugin's worktree lifecycle, not claude-ops; fix(source-control): worktree teardown leaves project-scope plugin install records forever #3113 attempted it and regressed, so it needs a root-cause pass first.
2. Stop creating the pins: drop project-scope enabledPlugins blocks that mirror the user scope across the fleet's repos. A repo-policy change spanning several repositories, not a plugin change.
3. Upstream ask: a prune-by-path verb. No code here; the no-reap-by-path claim it depends on was re-verified on 2.1.261 in docs(claude-ops): re-verify plugins skill probes against Claude Code 2.1.261 #3760.

None of the three touches the 755 already-stranded records, which only a direct installed_plugins.json edit (outside every plugin skill's boundary) or an upstream verb can reach.

RECOMMENDED: route 1 as the durable fix (it is the only one that stops growth without hand-editing state), reopened as a source-control worktree-teardown item with #3113's regression as its first step; route 3 filed upstream in parallel; route 2 left to per-repo judgement. A one-off, operator-run cleanup of the 12 absent-path record sets is a separate decision (hand edit of installed_plugins.json with a backup) and should be its own scoped item if wanted.

[kyle-sexton]

Review panel findings (2026-09-05), superseding the three-route framing above

Five independent reviews (architecture, operability, simplicity, plugin-scope docs, cloud/routines docs) against a written proposal. What they established, with doc citations where they exist:

The repo enabledPlugins block is doing two jobs, and they cannot be separated by shrinking it.

• Cloud: it is the native cloud installer. cloud-environments docs: plugins declared in .claude/settings.json are "installed at session start from the marketplace you declared." cloud-bootstrap.sh's plugin loop re-implements this built-in.
• Local: the same block is what produces the project-scope pins. All 64 records for this repo's path were written in one second, a session-start batch. Docs say local sessions need an explicit install for external-source plugins, so exactly what writes them locally is unverified and needs a probe (fresh worktree, watch installed_plugins.json).
• Consequence: reducing the block to per-repo deltas removes the cloud install for every plugin removed. Any fix must relocate the fleet list for cloud before touching the blocks.

Account-level sync does not rescue it. @synced plugins load only in cloud and Cowork sessions, never in local terminals (plugins-reference, "Synced plugins"), so they cannot replace the dotfiles seed; and account-level enablement of a custom GitHub marketplace on a personal account is undocumented (only Team/Enterprise org distribution is documented).

Precedence corrections. enabledPlugins merges managed > --settings > local > project > user (settings-reference). Project beats user, so a project false disables; "user scope wins" in the original issue referred to which version path loads, not enabled state. Whether a project false writes an install record is undocumented.

No prune-by-path exists and the retention sweep explicitly excludes ~/.claude/plugins/ (claude-directory, "Cleaned up automatically"). Changelog 2.1.224 ("install records silently corrupted when the same plugin is installed in multiple projects") confirms per-project records are a live, fragile mechanism. Nothing since 2.1.200 changes pin behaviour.

Design and simplicity. Four fleet lists already exist (standards' own .claude/settings.json, components/claude-settings/base, the dotfiles seed with 86 entries, and every repo block). No repo uses per-repo deltas today: 70 to 72 true entries and zero false anywhere. Preserving per-repo customisation is not a requirement the evidence supports. cloud-environment/setup.sh has its own independent enabledPlugins install loop that any change must cover.

How the surfaces are actually managed today

Surface	Owner	Mechanism
Personal machines (Windows, WSL)	dotfiles (chezmoi)	.chezmoidata/claude.json seeds 86 entries into user settings; a run_ script installs every seeded id at user scope; CI gates the seed against every marketplace manifest
Cloud VMs	standards cloud-bootstrap (materialised per repo) plus cloud-environment/setup.sh at snapshot build	both read the repo's committed enabledPlugins and install at user scope on the VM
Per-repo committed block	each repo	70 to 72 true; claude-code-plugins additionally gates it against its catalogue for cloud dogfood
provisioning	not involved	elevated host state only; carries a mirrored block like any other repo

Revised recommendation

Move the fleet list for cloud out of repos and into the account-scoped environment, then delete the repo blocks.

1. standards cloud-environment/setup.sh installs the fleet set at user scope on the VM at snapshot build from one standards-hosted list (raw.githubusercontent.com is on the default allowlist). That list becomes the single fleet SSOT for cloud; claude-settings/base's block and the standards-settings baseline retire. Environments are personal, attach to many repos, and routines reuse the snapshot.
2. Repos delete the mirrored block, keeping extraKnownMarketplaces plus genuine deltas only (true for a project-only plugin, false to opt out). Native session-start install then handles only those deltas.
3. cloud-bootstrap.sh's plugin loop shrinks to user-scope drift repair on the ~7-day-stale snapshot (update, not install), with a fallback that still installs from enabledPlugins until every repo has dropped its block. The two locally-owned copies (claude-code-plugins, medley) are hand-edited.
4. Dotfiles unchanged. One standards check compares the cloud list with the dotfiles seed so the two surviving lists cannot drift.
5. claude-code-plugins' dogfood gate becomes "catalogue is a subset of the standards cloud list".
6. Laptop cleanup last: Claude closed, timestamped backup, jq transform to a temp file validated with jq -e before replacing, backup kept until one clean session and one chezmoi apply converge.
7. Upstream asks: project true should not pin when the user scope already has the plugin; a prune-by-path verb.

Probes required before shipping (both undocumented and load-bearing): what writes local project records when a repo enables plugins the user already has; whether a project false writes a record.

Order: probes, standards (list + setup.sh + bootstrap fallback + drift check), verify one cloud session per repo installs from the snapshot, repo block deletions (claude-code-plugins first, gate repointed), remove the fallback, laptop cleanup.

Status: needs-decision. Approval of this shape is the gate; it then decomposes into a standards PR followed by one small PR per repo.

[kyle-sexton]