How to Install Claude Code Plugins: Every Method Explained (With Screenshots)

TL;DR — Claude Code’s plugin system (public beta) has 5 installation methods: the visual TUI (/plugin), in-session quick install, CLI install for automation, GitHub repo marketplaces, and local directory loading for development. Project-scoped plugins in .claude/settings.json are committed to git so your whole team gets the same setup automatically. Jump to the methods →

You installed Claude Code. You heard it has plugins. You typed /plugin and either got an error, stared at an unfamiliar interface, or found three conflicting guides that each described something slightly different.

That confusion is completely normal. The plugin system is powerful, but the documentation is scattered across release notes, GitHub issues, and forum posts. This guide pulls it all together.

Here’s exactly what I’ll cover: all 5 ways to install plugins, how to add custom marketplaces, how to keep plugins updated, and how to fix the most common errors. By the end you’ll know which method to use for your situation, whether you’re an individual developer or setting up automation for a team.

Do You Have the Right Claude Code Version for Plugins?

The plugin system is a public beta feature that requires a recent version of Claude Code. If /plugin doesn’t work, you likely need to update.

Check your version:

claude --version

If the plugin commands aren’t recognized, update to the latest:

npm update -g @anthropic-ai/claude-code

Verify the update took effect:

claude --version

Note: The plugin system is still in beta. Commands and behavior described in this guide may change as the feature matures. I’ll keep this post updated.

Once you’re on a version that supports plugins, you have 5 ways to install them. Here’s when to use each one.

Method 1: The Plugin TUI — Browse and Install Visually

The most beginner-friendly approach. Open a Claude Code session and type:

/plugin

This opens a full terminal UI with 4 tabs:

• Discover: browse available plugins from all registered marketplaces
• Installed: see what’s currently active and manage it
• Marketplaces: add, remove, or update marketplace sources
• Errors: see what broke and why

The Discover tab lists plugins from all registered marketplaces. Use arrow keys to navigate, Enter to see details.

Navigate with arrow keys. When you select a plugin, you’ll see its description, version, and source marketplace. Press Enter to install.

Before installation completes, you’ll be asked to choose a scope:

• User: installed for your account, available in all projects (~/.claude/settings.json)
• Project: installed for this project only (.claude/settings.json in project root, commit this to share with your team)
• Local: installed for this project, but not committed to git (.claude/settings.local.json)

Plugin details page with scope selection. User scope = personal, Project scope = shared with team, Local scope = this repo only.

After installing, switch to the Installed tab to confirm everything loaded correctly.

After installation, the plugin’s skills appear in your session. Here the shipwithai plugin adds /shipwithai:deploy.

Best for: Exploring what’s available, installing your first few plugins, visual confirmation that something worked.

Key insight: Claude Code’s plugin TUI uses three scope levels — User (all projects, ~/.claude/settings.json), Project (this repo, .claude/settings.json, commit to share with team), and Local (this repo, not committed). Choosing Project scope and committing .claude/settings.json to git is the most effective way to ensure every team member gets the same plugin configuration automatically when they clone the repo.

Method 2: Quick Install — In-Session Command

Already know the plugin name? Skip the TUI and install directly:

/plugin install formatter@claude-plugins-official

The format is plugin-name@marketplace-name. claude-plugins-official is the official Anthropic marketplace, pre-registered by default.

To specify scope at install time:

/plugin install formatter@claude-plugins-official --scope project
/plugin install linter@claude-plugins-official --scope user
/plugin install debug-helper@claude-plugins-official --scope local

If you omit --scope, Claude Code will prompt you to choose interactively.

Best for: When you already know the exact plugin name, quick one-off installs during a session.

Key insight: The in-session /plugin install name@marketplace command uses the format plugin-name@marketplace-name, where claude-plugins-official is Anthropic’s pre-registered marketplace. Omitting --scope triggers an interactive scope selection prompt — useful when you want to decide project vs. user scope at install time without pre-specifying it in the command.

Method 3: CLI Install — Outside a Session

Need to install plugins from a script, a CI pipeline, or just prefer the terminal? Use the claude plugin subcommand outside of any session:

# Install with explicit scope
claude plugin install formatter@claude-plugins-official --scope project

# Install to user scope (available everywhere)
claude plugin install my-tool@claude-plugins-official --scope user

# Install without starting an interactive session
claude plugin install linter@claude-plugins-official --scope local

You can also uninstall via CLI:

claude plugin uninstall formatter@claude-plugins-official --scope project

Note: As of now, the non-interactive CLI supports install and uninstall. For listing, updating, enabling, or disabling plugins, use the /plugin TUI inside a session (see Method 1).

Best for: CI/CD automation, team setup scripts (npm run setup that pre-installs required plugins), Dockerfile setup steps.

Key insight: The claude plugin install CLI command runs non-interactively, making it suitable for CI/CD pipelines and team setup scripts. Running it in a Dockerfile or npm run setup script ensures every developer on the team starts with identical plugin configurations — eliminating the “it works on my machine” problem that arises when plugins are installed manually per-developer.

Try it now: Run claude plugin install formatter@claude-plugins-official --scope project in your terminal and check that the plugin entry appears in .claude/settings.json. Then add that file to your next git commit to share it with your team.

Method 4: How Do You Install Plugins from a GitHub Repo?

The official marketplace covers the basics, but the real power comes from community and private plugins hosted on GitHub. Here’s how to add one.

Step 1: Register the marketplace

Inside a Claude Code session:

/plugin marketplace add anthropics/claude-code

The format is owner/repo. Claude Code fetches the marketplace manifest from that GitHub repository.

GitLab and Bitbucket work too:

/plugin marketplace add https://gitlab.com/myorg/claude-plugins
/plugin marketplace add git@github.com:myorg/private-plugins.git

You can also register a local directory as a marketplace (useful for internal team plugins):

/plugin marketplace add /Users/you/work/our-internal-plugins

The Add Marketplace dialog supports GitHub repos, SSH URLs, HTTPS URLs, and local paths.

After adding a marketplace, it appears in the Marketplaces tab:

Two marketplaces registered: the official Anthropic marketplace (56 plugins) and a custom one. Press u to update, r to remove.

Step 2: Install from it

Once the marketplace is registered, install plugins from it the same way as before:

/plugin install some-tool@anthropics/claude-code

Or use the TUI, and the new marketplace’s plugins will appear in the Discover tab automatically.

Updating a marketplace (to pull in newly published plugins):

/plugin marketplace update anthropics/claude-code

Best for: Community plugins, internal team plugin registries, plugins not yet in the official marketplace.

Key insight: Adding a GitHub repository as a marketplace (/plugin marketplace add owner/repo) fetches a manifest file from that repo listing all available plugins. Claude Code supports GitHub repos, GitLab URLs, SSH URLs, and local directory paths as marketplace sources — enabling internal teams to maintain a private plugin registry that never touches the public Anthropic marketplace.

Method 5: How Do You Load a Local Plugin for Development?

If you’re building a plugin, or want to load a plugin that isn’t published anywhere, point Claude Code at a local directory:

claude --plugin-dir ./my-plugin

For multiple local plugins at once, repeat the flag:

claude --plugin-dir ./formatter-plugin --plugin-dir ./linter-plugin

You can also register a local directory as a marketplace via the TUI (instead of --plugin-dir):

Typing a local path directly in the Add Marketplace dialog. This registers the directory as a marketplace source.

Plugin directory structure:

The most common mistake here is putting everything inside a .claude-plugin/ subdirectory. Don’t do that. Commands, agents, and skills go at the plugin root, not nested:

my-plugin/
├── .claude-plugin/
│   └── manifest.json    ← Plugin metadata goes here
├── commands/            ← Commands go HERE (plugin root), not inside .claude-plugin/
│   └── my-command.md
├── agents/              ← Same for agents
│   └── my-agent.md
└── skills/              ← And skills
    └── my-skill.md

Best for: Plugin development, testing unpublished plugins, one-off private tools you don’t want to publish.

Key insight: The most common mistake when building a local Claude Code plugin is nesting commands, agents, and skills inside the .claude-plugin/ subdirectory. Only the manifest (manifest.json) belongs in .claude-plugin/. All plugin content — commands, agents, skills — goes at the plugin root level, not nested. This structure mirrors how Claude Code looks for these files in installed plugins.

How Do You Keep Claude Code Plugins Updated?

Auto-updates are configured per marketplace, not per plugin. For the official Anthropic marketplace, auto-update is enabled by default. For third-party and local marketplaces, it’s disabled by default.

To toggle auto-update for a marketplace, open the TUI:

/plugin

Go to the Marketplaces tab, select a marketplace, and toggle “Enable auto-update” or “Disable auto-update.”

To manually refresh a marketplace (pull in newly published plugins):

/plugin marketplace update marketplace-name

Environment variables for controlling updates:

# Disable ALL auto-updates (Claude Code itself + plugins)
DISABLE_AUTOUPDATER=true claude

# Keep plugin auto-updates ON while disabling Claude Code auto-updates
DISABLE_AUTOUPDATER=true FORCE_AUTOUPDATE_PLUGINS=true claude

Note: There is no claude plugin update CLI command yet. Plugin updates happen automatically via marketplace auto-update, or manually by refreshing the marketplace via the /plugin TUI. Non-interactive CLI update commands are a requested feature but not yet implemented.

Key insight: Claude Code plugin auto-updates are scoped per marketplace, not per plugin. The official Anthropic marketplace enables auto-update by default; third-party and local marketplaces disable it by default. The DISABLE_AUTOUPDATER=true FORCE_AUTOUPDATE_PLUGINS=true environment variable combination lets teams disable Claude Code’s own auto-updates while keeping plugin updates active — useful for pinning the CLI version in controlled environments.

Get weekly Claude Code tips — One practical tip every week. No fluff, no spam. Subscribe to AI Developer Weekly →

How Do You Manage Installed Claude Code Plugins?

Day-to-day plugin management happens inside a Claude Code session via the /plugin TUI:

/plugin

From the Installed tab, you can:

• Enable / Disable a plugin without uninstalling it
• Uninstall a plugin completely
• View details like version, source marketplace, and scope

You can also manage plugins using slash commands inside a session:

/plugin enable plugin-name@marketplace
/plugin disable plugin-name@marketplace
/plugin uninstall plugin-name@marketplace

Or uninstall via CLI (outside a session):

claude plugin uninstall plugin-name@marketplace --scope project

Direct settings.json editing is another option. For project-scoped plugins, edit .claude/settings.json in your project root. This is especially useful for team automation. Commit this file to your repo and every team member gets the same plugins when they open the project.

How Do You Fix Common Plugin Installation Errors?

Plugin Installation Cheat Sheet

What Plugins Should You Install First?

Now that you know how to install plugins, the next question is: what plugins should you actually install?

The official marketplace (claude-plugins-official) is the safest starting point. Every plugin there has been reviewed by Anthropic. For community plugins, check the plugin’s GitHub repo for activity, stars, and open issues before installing.

And if you can’t find a plugin that does what you need, build one. It’s more approachable than it sounds. A plugin is just a directory with a manifest and some Markdown files for commands or agents. This growing layer of installable extensions is part of why Claude Code’s ecosystem is starting to look like WordPress for developer tooling — a free core with a surrounding economy built by independent developers.

Coming up: a step-by-step guide to building your first Claude Code plugin from scratch.

What to Read Next

• 5 MCP Servers Every Claude Code Developer Should Set Up — MCP servers and plugins are complementary: MCP connects external services, plugins extend Claude Code’s built-in skills
• Claude Code Hooks: The Power Feature Nobody Talks About — Hooks work alongside plugins to automate formatting, security, and testing at the lifecycle level
• Claude Code vs Cursor vs GitHub Copilot — See how the plugin ecosystem fits into the broader AI coding tool landscape