Claude Code plugin scope: user, project or local?

Every claude plugin install picks a scope, and the default is easy to miss. The scope decides which settings file records the plugin, who else gets it, and whether it follows the project through git. Tested on Claude Code v2.1.296 (October 2026); real paths and output below.

The three scopes

The flag is -s (or --scope) with three values:

• user (default) - recorded in your account's settings under your home directory. The plugin is available in every project on your machine, for you only.
• project - recorded in the project's .claude/settings.json. This file is meant for version control, so the plugin is shared with everyone who works on the repository.
• local - recorded in the project's .claude/settings.local.json, which is the uncommitted counterpart: project-specific and private to you.

What actually gets written

Verified on v2.1.296. Running this inside a git repository:

claude plugin install productivity@knowledge-work-plugins -s project

created .claude/settings.json containing exactly:

{ "enabledPlugins": { "productivity@knowledge-work-plugins": true } }

A -s local install of another plugin in the same project created .claude/settings.local.json with the same shape. The user-scope default writes to your home settings instead, leaving the project untouched.

claude plugin list confirms the result per plugin: version, scope and enabled status on one line each.

Which one to pick

• Just you, everywhere: user. Your personal toolkit follows you between projects.
• The team needs it: project. Committing .claude/settings.json means a teammate clones the repo and gets the same plugins enabled. This is the scope for shared tooling like a release-notes or review plugin.
• Trying something in one repo: local. Nothing lands in git, nothing leaks to teammates, and deleting the line reverts it.

A plugin installed at two scopes is not a conflict worth fearing; the more specific setting wins for that project. If a teammate reports a plugin missing, the first check is whether it was installed at user scope on your machine and never committed - the classic project-scope miss.

Related commands

• Re-scope is just reinstall with a different -s; the settings file moves the entry.
• claude plugin disable <plugin> flips the enabled flag without removing anything.
• Skills-directory plugins from claude plugin init are always user-scope and machine-local; sharing them means packaging. See create a minimal plugin and install from a marketplace.

Sources

• Plugins reference - Claude Code Docs
• Commands and outputs: Claude Code v2.1.296, run October 10, 2026