Point --plugin-dir at a plugin folder

Test your plugins locally

Use the --plugin-dir flag to test plugins during development. This loads your plugin directly without requiring installation.

claude --plugin-dir ./my-plugin

The flag also accepts a .zip archive of the plugin directory.

claude --plugin-dir ./my-plugin.zip

When a --plugin-dir plugin has the same name as an installed marketplace plugin, the local copy takes precedence for that session. This lets you test changes to a plugin you already have installed without uninstalling it first. The exception is plugins that managed settings force-enable or force-disable: --plugin-dir cannot override those.

As you make changes to your plugin, run /reload-plugins to pick up the updates without restarting. This reloads plugins, skills, agents, hooks, plugin MCP servers, and plugin LSP servers; in a session without an interactive terminal, plugin MCP server changes wait for your next session. Test your plugin components:

• Try your skills with /plugin-name:skill-name
• Check that agents appear in /context under Custom Agents, or @-mention one by its scoped name
• Trigger the event each hook matches, such as asking Claude to edit a file for a PostToolUse hook, and confirm its effect. Claude Code records which hooks matched, their exit codes, and their output in the debug log

You can load multiple plugins at once by specifying the flag multiple times:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

To test a plugin together with a plugin it depends on, see Test a plugin and its dependency locally.

To load plugins in a session where you can't add the flag, list their absolute paths in the CLAUDE_CODE_PLUGIN_DIRS environment variable instead. Claude Code loads each path as it loads a --plugin-dir path. These plugins load in addition to any you pass with --plugin-dir. Project and local settings can't set this variable. CLAUDE_CODE_PLUGIN_DIRS requires Claude Code v2.1.280 or later.

Trying the plugin with --plugin-dir tells you it can work. To find out how often Claude actually reaches for it and gets the right result, run it against a set of test prompts with claude plugin eval. Each prompt runs several times with and without the plugin loaded, so you can see what the plugin contributes and catch regressions when you change it or a new model ships.

To load several plugins from one place, pass a folder that holds them, such as --plugin-dir ./plugins. Loading a folder of plugins requires Claude Code v2.1.265 or later. Claude Code reads the folder's top level to decide which plugins load, and in an interactive session it also watches the folder for later changes:

• What loads: if the folder has no manifest or plugin components at its top level, Claude Code treats it as a folder of plugins. Each immediate subfolder that has a .claude-plugin/plugin.json manifest loads as a separate plugin. Claude Code skips everything else in the folder without reporting an error, including plugins that have no manifest.
• Changes during an interactive session: a subfolder you add loads as a new plugin once its manifest is in place, and when you remove a subfolder, its plugin unloads. Claude Code prints a line in the session for each change. If applying a change mid-conversation would invalidate the prompt cache, Claude Code holds it, and the line says to run /reload-plugins to apply it.

To test a plugin that is already packaged as a .zip archive and hosted at a URL, such as a CI build artifact, use --plugin-url instead. Claude Code fetches the archive at startup and loads it for that session only. If Claude Code can't fetch the archive, or the archive is invalid, it starts without the plugin and records a plugin load error that you can review in the /plugin manager's Errors tab. The same trust considerations apply as for any plugin source: only point this flag at archives you control or trust.

To load multiple plugins, repeat the flag for each URL:

claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

Or pass space-separated URLs as one quoted argument:

claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"