Install and manage plugins

This page takes you from "someone told me about a plugin" to having it installed, scoped correctly and kept up to date. It covers the terminal, the desktop app, VS Code, scripts and cloud sessions.

If the install command you were given ends in something other than @claude-plugins-official, you need to add that marketplace first. If Claude Code printed an error, jump to /docs/plugins/troubleshooting.

Install a plugin

The worked example below installs commit-commands from Anthropic's official marketplace. It adds skills for committing, pushing and opening pull requests. Swap in any other plugin@marketplace and the steps are identical.

In the terminal

1. Open the details pane. Inside a session, run:

   /plugin install commit-commands@claude-plugins-official
   

   Copy

   In a session this does not install straight away. It opens the /plugin panel on the plugin's details so you can look before committing. Running /plugin on its own opens the Discover tab instead, where you can type to search and press Enter on a result.

2. Read what it adds. The pane shows the description and, where available:

   • Will install: the commands, agents, skills, hooks, and MCP and LSP servers.
   • Last updated: for official marketplace plugins.
   • Context cost: for official marketplace plugins, two token estimates. Every turn is what it adds to each message; When invoked is what its skills and agents add once loaded. These figures appear when you open the plugin by naming its marketplace (as above) or from the Marketplaces tab, not from the Discover list.

   Local or custom marketplaces may just say Components will be discovered at installation. Plugins can run hooks and servers, so read this before going further; see /docs/plugins/security.

3. Pick a scope. The three options are Install for you (user scope), Install for all collaborators on this repository (project scope) and Install for you, in this repo only (local scope). Claude Code installs the plugin plus any declared dependencies and prints a summary.

4. Check the last line of the summary.

   Message	Meaning
   Plugin is now active.	Ready to use, no reload
   Plugin is now active. then Its bundled MCP server needs configuration before it can start	Open the plugin on the Installed tab and choose Configure
   Run /reload-plugins to apply.	Claude Code closes the panel and reloads for you. If that would invalidate the prompt cache it warns and leaves the plugin pending; /reload-plugins --force applies it at the cost of one uncached request
   The plugin couldn't be loaded	Check the Errors tab in /plugin

5. Confirm it works. Type / and look for /commit-commands:commit. The Installed tab and claude plugin list (with Version, Scope and Status lines) also list it.

The Claude Code button on a plugin's page at claude.com/marketplace copies the shell form, claude plugin install <name>@claude-plugins-official.

In the desktop app

In a local or SSH session on the Code tab, click + beside the prompt box, choose Plugins, then Add plugin. Select the plugin and choose user, project or local scope. Manage it later through + > Plugins > Manage plugins. The plugin browser is not available in the desktop app's cloud sessions. See /docs/desktop.

In VS Code

Type /plugins in the Claude Code panel to open Manage plugins. On the Plugins tab, search and click Install, then choose Install for you, Install for this project or Install locally. If the list is empty, add anthropics/claude-plugins-official on the Marketplaces tab. Changes reach open sessions without a restart. See /docs/vs-code.

In a cloud session

Cloud sessions, including claude.ai/code, have no plugin browser and load neither your machine's plugins nor those switched on in the repository's .claude/settings.json. Organisation-distributed plugins arrive through managed settings; see /docs/plugins/org and /docs/cloud-environments.

JetBrains, claude -p and the Agent SDK

• JetBrains: Claude Code runs in the IDE terminal, so follow the terminal steps.
• Non-interactive runs: /plugin replies /plugin isn't available in this environment. Installed plugins still load. Use the shell commands.
• Agent SDK: pass plugins through the SDK's plugin option; see /docs/agent-sdk/plugins.

Tip: Testing your own plugin? Skip installing and run claude --plugin-dir ./my-plugin for a one-session load. See /docs/plugins/cli-reference.

Choose an install scope

Project scope switches the plugin on for collaborators but does not download it for them. Each person runs claude plugin install <name>@<marketplace> --scope project once. If they forget, Claude Code tells them; see /docs/plugins/loading.

When the same plugin appears at several scopes, local beats project and project beats user.

Some authors ship plugins switched off by default with the defaultEnabled field. Those install but stay off until you run claude plugin enable <name> or toggle them on the Installed tab.

Plugins from your claude.ai account

Your claude.ai account is another plugin source. Plugins you switch on there, and those your organisation switches on for members, sync into terminal sessions in the background each time you start Claude Code signed in with that account. They appear as <name>@synced in /plugin and claude plugin list, and you can turn one off at your own scope unless your organisation requires it. Sync is one way: plugins you install locally are not pushed to claude.ai. Synced plugins need Claude Code v2.1.273 or later; /docs/plugins/loading covers timing and how to switch sync off.

Install from your shell

claude plugin install works without opening a session, which makes it ideal for onboarding scripts:

#!/usr/bin/env bash
# new-starter.sh: register our marketplace and install the team plugins
claude plugin marketplace add acme-eng/claude-plugins
claude plugin install pr-hygiene@acme-plugins --scope user
claude plugin install service-scaffold@acme-plugins --scope user

• The default scope is user. Pass --scope project or --scope local to change it.
• New plugins load the next time Claude Code starts, or on /reload-plugins in an open session.
• On a machine that has never run an interactive session, the official marketplace is not registered yet, so run claude plugin marketplace add anthropics/claude-plugins-official before installing from it.
• Success prints Successfully installed plugin: <name>@<marketplace> (scope: <scope>).
• Some plugins install via a command source that Claude Code asks you to approve. A script cannot answer that prompt, so pass --yes.

All flags are in /docs/plugins/cli-reference.

Add a marketplace

You only need this for plugins outside the official marketplace. Add the marketplace once; its plugins then show on Discover and install by <plugin>@<marketplace>, where <marketplace> is the name it registered under.

Run /plugin marketplace add <source> in a session, or claude plugin marketplace add <source> in your shell. /plugin market is accepted as a short form.

Always include https:// on URLs, or use git@host:path for SSH. A bare git.acme.internal/tools/plugins.git is read as GitHub owner/repo shorthand and rejected.

On success you see Successfully added marketplace: <name> and the plugins appear on Discover next time you open /plugin, with no reload.

Add and install in one go

On v2.1.275 or later you can install from a marketplace you have not added yet:

/plugin install release-notes --marketplace acme-eng/claude-plugins

Give the bare plugin name, no @ suffix. The source takes the same forms as above but cannot contain spaces. Claude Code shows the resolved source and asks you to confirm before adding it, then opens the plugin's details. If the marketplace is already registered, it skips the confirmation.

Private marketplaces

Private repositories use the same commands. Claude Code clones with the git credentials already on your machine and never prompts:

• HTTPS: your credential helpers apply (gh auth login, macOS Keychain, git-credential-store). Interactive prompts are suppressed, so an unauthenticated host fails rather than asking.
• SSH: the host must already be in known_hosts and the key must work without a passphrase prompt. A program named in GIT_SSH_COMMAND, GIT_SSH or core.sshCommand is honoured.
• owner/repo shorthand: Claude Code checks whether your SSH key authenticates to github.com and uses SSH if so, HTTPS otherwise. Set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 to always use HTTPS.

The same credentials are used by /plugin install, /plugin marketplace update and claude plugin update. For GitHub Enterprise Server see /docs/github-enterprise-server. If your organisation registers the marketplace through managed settings, you do not add it yourself.

Marketplaces listed by claude.ai

When plugin sync is on (v2.1.273 or later), claude.ai can offer marketplaces such as your organisation's plugin library. Add these by name, not source: pick one on the Marketplaces tab of /plugin, or run claude plugin marketplace list, find it under From claude.ai:, and run:

claude plugin marketplace add --claudeai claudeai-organization-library

The local name always starts with claudeai-, derived from the listed name ("Organization library" becomes claudeai-organization-library). If you sign out or switch organisation, the marketplace stays configured but empty, and installed plugins keep loading. Git-based marketplaces shared through claude.ai show a source in that list; add those by source, not --claudeai.

Manage installed plugins

Open /plugin and press Tab to reach Installed, or jump straight there with /plugin enable, /plugin disable or /plugin uninstall. Disabled plugins collapse under a header at the bottom.

• Type to filter by name or description.
• Space toggles enabled; f marks a favourite.
• Enter opens details with Enable/Disable plugin, Update now and Uninstall.
• Configure options appears if the manifest declares userConfig; Configure appears for a bundled MCP server's own user_config.

Plugins at Managed scope come from your organisation and cannot be changed here. When you close the panel with pending changes, Claude Code runs /reload-plugins (or warns and waits if that would break the prompt cache; --force overrides).

Synced plugins

Synced plugins show synced as their source. Enable or disable them on Installed unless required; remove them by turning them off on claude.ai. When sync changes something mid-session you see Plugins changed. Run /reload-plugins to activate.

Uninstalling a project-enabled plugin

If the repo's .claude/settings.json enables the plugin, uninstalling asks you to choose: press y to disable it just for you (writes false into .claude/settings.local.json) or u to remove it from the shared file for everyone.

Footprint and idle plugins

claude plugin details <name> shows an Always-on token figure plus per-component rows; see /docs/plugins/measure. On Installed, plugins you have not used lately sit under Not used recently, and details show Last used. I prune that group roughly monthly.

Dependencies

When a marketplace plugin declares dependencies:

• Install also installs and enables them at the same scope.
• Enable also enables installed-but-disabled dependencies, and fails if one is missing.
• Disable refuses while another enabled plugin needs it, and prints a chained command to disable both in order.
• Uninstall leaves auto-installed dependencies until you run claude plugin prune.

See /docs/plugins/dependencies.

From the shell

claude plugin disable pr-hygiene@acme-plugins
claude plugin enable pr-hygiene@acme-plugins
claude plugin uninstall pr-hygiene@acme-plugins --scope project

enable and disable default to the most specific scope that already lists the plugin. install and uninstall default to user scope.

Keep plugins updated

When a marketplace has auto-update on, Claude Code refreshes it after a session starts and updates installed copies on disk. The running session keeps what it loaded; you see Plugin updated: <name> · Run /reload-plugins to apply, and new sessions pick it up.

• On by default: claude-plugins-official and the other official names except knowledge-work-plugins and first-party-plugins, plus marketplaces added from claude.ai.
• Off by default: everything else, including the community marketplace, third-party and local marketplaces.

Toggle it per marketplace on the Marketplaces tab with Enable auto-update or Disable auto-update. Rules and environment variables are in /docs/plugins/loading.

To update now, choose Update now on a plugin or run claude plugin update <plugin>@<marketplace>. There is no update-everything command. Update marketplace on the Marketplaces tab refreshes the listing and updates every plugin from it, except those with a command source or a headersHelper entry, which you update individually. claude plugin marketplace update with no name refreshes all listings but leaves installed plugins alone.

For private marketplace credentials during background updates, see /docs/plugins/host-marketplace.

Manage marketplaces

Warning: Removing a marketplace uninstalls every plugin you installed from it and deletes their enabledPlugins entries. The Marketplaces tab lists them before you confirm.

Related

• Plugins overview
• Anthropic's marketplaces
• Plugin loading reference
• Plugin security and trust
• Troubleshoot plugins