plugin-embedder

plugin-embedder

A Claude Code plugin whose only job is to embed OTHER plugins into a target repo as project-local plugins. Reads .claude/embedded-plugins.json in the target repo, clones each listed source, and drops the wholesale plugin tree into .claude/plugins/<plugin-name>/. Updates .claude/settings.json to enable the embedded copies and disable any matching marketplace copies.

Why this exists

Claude Code Web containers, restricted-network CI runners, and other constrained environments don't reliably install plugins from marketplaces. Project-local plugins (the convention Anthropic's own pr-review-toolkit uses — full plugin tree under .claude/plugins/<name>/, enabled by bare name) work everywhere because the content is right there, committed to the consuming repo's git history.

plugin-embedder mechanizes that pattern. A consuming repo declares which plugins it wants embedded in a small manifest; the embed script syncs the embedded trees from the upstream sources whenever the maintainer runs it.

Install

User-level (just for you, across all repos)

claude plugin marketplace add ZainRizvi/plugin-embedder
claude plugin install plugin-embedder@plugin-embedder

That gives you the /plugin-embedder:embed-plugins skill globally. Run it from any repo that has a manifest.

Project-level

You generally don't need to install plugin-embedder in the consuming repo — the embedded plugin content is what the consuming repo carries. Just install plugin-embedder once on your maintainer machine and use it to keep embedded content fresh in any repos you maintain.

Usage

In the consuming repo, commit a manifest at .claude/embedded-plugins.json:

{
  "plugins": [
    { "source": "github:owner/some-plugin", "ref": "main" },
    { "source": "github:other/other-plugin" }
  ]
}

ref defaults to main. Plugin name comes from each source's own .claude-plugin/plugin.json.

Then run the embed (manually, when you want to refresh). Easiest is the skill:

/plugin-embedder:embed-plugins

If you'd rather run the script directly (e.g., from a Makefile), invoke it via ${CLAUDE_PLUGIN_ROOT} so the path doesn't pin to a specific plugin version:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/embed-plugins.sh"

The script:

• Clones each listed source (shallow, to the manifest's ref).
• Wipes the prior .claude/plugins/<plugin-name>/ for each listed plugin and re-copies the new tree (without upstream's .git).
• Updates .claude/settings.json: enables the embedded copy ("<name>": true), disables any matching marketplace entry ("<name>@<marketplace>": false) so hooks don't fire twice.
• Idempotent — re-runs refresh embedded copies.

Diff, review, commit:

git status
git diff .claude/settings.json
git add .claude/plugins .claude/settings.json
git commit -m "Refresh embedded plugins"

Layout

.claude-plugin/
  plugin.json                 # plugin manifest
  marketplace.json            # marketplace entry (single-plugin repo)
scripts/
  embed-plugins.sh            # the workhorse
skills/
  embed-plugins/SKILL.md      # user-invocable skill

Requirements

• bash, git, jq — the embed script preflight-checks git and jq and bails loudly if missing. tar and mktemp are also used (POSIX-standard, assumed present).
• The consuming repo must have a .claude/embedded-plugins.json manifest. Embed script bails if missing.

Limitations

• Source repos must have .claude-plugin/plugin.json at the repo root. Plugins living in a subdirectory of a monorepo aren't supported (no path field in the manifest yet).
• ref must be a branch or tag. Raw commit SHAs don't work — git clone --branch <sha> rejects them. Pin to a tag for reproducibility instead.
• Don't run two embeds against the same target repo concurrently. The wipe+re-copy step isn't atomic. Sequential invocations are safe.

What plugin-embedder is NOT

• Not a way to install plugins for daily personal use — for that, claude plugin install <slug> is the right tool.
• Not a marketplace replacement. The upstream sources still need to be valid Claude Code plugins; embedding only avoids the install step on the consumer side.
• Not automated. Each refresh is a deliberate, committed-to-the-repo action by the maintainer.

See also

• git-workflow-guards — git/PR-workflow guards. Designed to be embeddable.
• webapp-toolkit — opinionated web-app skills. Designed to be embeddable.

License

MIT — see LICENSE.