What
--plugin-dir accepts either a single plugin or a folder holding several plugins. Its debug message, the detailed log you can turn on, now says what marks a folder as a single plugin. When a folder has nothing at its top marking it as one plugin, the message says so. It also says when a marketplace root was loaded as a folder of plugins.
Why
If a plugin does not load the way you expected, the log tells you how Claude Code read the folder and why.
Names in the bundle--plugin-dir
The entry above is what we published on the day. These lines were added later, as Anthropic's own pages caught up, and they sit beside the original rather than replacing it.
Confirmed since
Anthropic's documentation has since written up --plugin-dir, on All settings.
Reject the `--plugin-dir`, `--plugin-url`, `--agents`, and `--mcp-config` CLI flags at startup, which users could otherwise pass to bypass [`strictKnownMarketplaces`](#strictknownmarketplaces) for a single run. Claude Code exits with an er…settings-reference see the edit
Added since
A small documentation edit on Week 20 · May 11–15, 2026 touched a line naming --plugin-dir after this was published.
<div><code>claude agents</code> gained dispatch flags (`--add-dir`, `--settings`, `--mcp-config`, `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, `--dangerously-skip-permissions`) to configure background sessions, and `claude a…whats-new/2026-w20 see the edit
Two sources agreeTwo things we can check say the same as this entry.
Anthropic's documentation agrees
A small documentation edit on Week 20 · May 11–15, 2026 touched a line naming --plugin-dir after this was published.
Anthropic's release notes agree
Fixed --plugin-dir on a folder of plugins that also has a .claude-plugin/marketplace.json loading one empty plugin instead of the plugins in…