Rolling a Claude Code plugin out to twenty repositories, what do the user, project and local install scopes each write, and which wins?
answer
- three settings files, one key
- enabledPlugins entries per plugin id
- local over project over user
- project scope enables, does not download
- extraKnownMarketplaces in committed settings
basics
~20 sEach scope writes an enabledPlugins entry: user to ~/.claude/settings.json, project to the committed .claude/settings.json, local to .claude/settings.local.json. Local beats project beats user, and a project entry turns an externally sourced plugin on without downloading it.
solid answer
~40 sThe scope names the settings file that records `"name@marketplace": true` under `enabledPlugins`: user scope (the default) writes `~/.claude/settings.json` for every project on the machine, project scope writes the committed `.claude/settings.json` for everyone in the repository, and local scope writes the gitignored `.claude/settings.local.json` for you in that repository. Entries merge per plugin id, and the highest source that mentions the id wins: local over project over user, with the `--settings` flag and managed settings above them. Committing a project entry turns the plugin on for collaborators but does not download an externally sourced plugin, so each one also runs `claude plugin install <name>@<marketplace> --scope project`, unless the marketplace lists it by relative path. To opt out of a project-enabled plugin, set it to `false` in `.claude/settings.local.json`.
code
json · 10 lines{
"extraKnownMarketplaces": {
"platform-tools": {
"source": { "source": "github", "repo": "example-org/platform-tools" }
}
},
"enabledPlugins": {
"team-toolkit@platform-tools": true
}
}go deeper
Recall the three scopes and their files: user in ~/.claude/settings.json, project in the committed .claude/settings.json, local in the gitignored .claude/settings.local.json.
Explain the per-id merge of enabledPlugins, why local beats project beats user, and how a developer opts out of a plugin the repository turns on.
Diagnose rollout gaps: project entries that enable but never download, extraKnownMarketplaces ignored until trust, plugins missing on the first -p turn, and cloud sessions loading none of it.
Decide whether a plugin should follow repositories or people, and how much to commit per repository versus delegating a fleet-wide requirement to managed policy.
## The question behind scopes When a team wants the same skills, reviewer agent, format hook and MCP servers in twenty repositories, the real decision is **who should get the plugin, and through which file**. A plugin's **install scope** answers both: it names the settings file that records the plugin as enabled, and therefore who that file reaches. Installation (fetching files into `~/.claude/plugins/`) and enablement (an entry in settings) are separate stages, and most rollout surprises come from confusing them. ## What each scope writes Every scope writes the same key, `enabledPlugins`, as `"<plugin>@<marketplace>": true`, into a different file: | Scope | File | Reaches | |---|---|---| | `user` (default) | `~/.claude/settings.json` | You, in every project on this machine | | `project` | `.claude/settings.json` (committed) | Everyone who works in the repository | | `local` | `.claude/settings.local.json` (gitignored) | You, in this repository only | In a session, the `/plugin` details pane offers the three as "Install for you", "Install for all collaborators on this repository" and "Install for you, in this repo only". From a shell or setup script, `claude plugin install <id> --scope user|project|local` does the same; `install` and `uninstall` default to `user`, while `enable` and `disable` act on the most specific scope that already lists the plugin. ## Which entry wins `enabledPlugins` merges **key by key**: for each plugin id, the value from the highest-precedence source that mentions it applies, and a source that is silent leaves the lower value in place. From lowest to highest: 1. A directory passed with `--add-dir` (only a `true` counts, and anything else overrides it). 2. User settings. 3. Project settings. 4. Local settings. 5. The `--settings` flag for that session. 6. Managed settings, whose `true` force-enables and `false` blocks; locking plugins for an organization is a separate topic. So a developer who sets a plugin to `false` in user settings still gets it in a repository whose project file says `true`; `/plugin` and `claude plugin list` say the project setting overrides the user one. The fix is a `false` in that repository's `.claude/settings.local.json`. Choosing **Uninstall** on a project-enabled plugin offers exactly that ("Disable for me") or removing it from the shared file for everyone. ## Project scope enables, it does not download Committing a project entry turns the plugin on for collaborators, but Claude Code **does not fetch an externally sourced plugin** from a project file alone. Each teammate sees `Plugin "<name>" is enabled in project settings but isn't installed` in the `/plugin` Errors tab until they run `claude plugin install <name>@<marketplace> --scope project` once. Two setups avoid that step: - **Relative-path plugins**: when the marketplace lists the plugin by a path inside itself, it loads from the marketplace copy, with no install record needed. - **Committed marketplace registration**: `claude plugin marketplace add example-org/platform-tools --scope project` writes `extraKnownMarketplaces` into `.claude/settings.json`, so every teammate gets the catalog. Those entries apply only after the teammate accepts the workspace trust dialog for the folder; in an untrusted folder they are ignored silently. ## Confirming the rollout on one machine Before committing the same block to twenty repositories, check one teammate's machine end to end: 1. `claude plugin list` prints each plugin with `Version`, `Scope` and `Status` lines, so you can see whether the project entry or a personal install is the one in effect. 2. The `/plugin` **Installed** tab shows the plugin with its scope, and a disabled-but-still-loading row names the source that overrode the user setting. 3. The `/plugin` **Errors** tab shows `Plugin "<name>" is enabled in project settings but isn't installed here` when the download step was skipped. 4. Typing `/` and finding `/<plugin>:<skill>` confirms the session actually loaded it. ## Rollout notes for twenty repositories - Commit the same `extraKnownMarketplaces` and `enabledPlugins` block to each repository, or ask developers to install at user scope if the plugin should follow people rather than repositories. - In `claude -p` and CI runs, plugins install in the background and can be missing from the first turn; `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` makes the run wait. - A cloud session, including claude.ai/code, loads neither your machine's plugins nor the ones a repository's `.claude/settings.json` enables. - The terminal, the desktop app's local sessions and the VS Code extension read the same files, so a user-scope install appears in all three.
- A developer disabled a plugin in ~/.claude/settings.json, yet it still loads in one repository. Why, and what is the fix?That repository's `.claude/settings.json` sets the plugin to `true`, and project settings outrank user settings for that id; `/plugin` and `claude plugin list` name the overriding source. The developer sets the id to `false` in `.claude/settings.local.json`, which outranks the project file, or picks "Disable for me" when uninstalling. If managed settings force it on, no user file can turn it off.
- In a CI job with claude -p, why can a project-enabled plugin's skill be missing on the first turn?In non-interactive runs, marketplaces and plugins install in the background after the session starts, so the first query can run before the plugin arrives. Setting `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` makes the run wait for the install. The repository's `extraKnownMarketplaces` entries also apply only in a folder whose trust was already accepted.
- Committing enabledPlugins alone downloads a GitHub-sourced plugin for every teammate.
- A user-level false always beats a project-level true.
- Local scope writes a file every teammate shares through git.
- Project scope is the default for claude plugin install.
- Repository extraKnownMarketplaces entries apply before the folder is trusted.