Skip to content

Extern ​

The vendor store for external Claude Code plugins, and the machinery that fills it. A plugin from the wider ecosystem gets downloaded once into the bank at harness/extern/{plugins,skills,commands,agents,hooks,mcps}/ (type-sorted by module kind), where the whole clone is kept (bloat stripped) alongside a manifest.json that maps what the plugin really needs, and from then on the installer places it into any project like a native part – prefixed so nothing collides, rewritten so its scripts still resolve outside a plugin cache, and merged into the project's settings. This is project-local by design: it never touches Claude Code's own global plugin machinery (~/.claude/plugins/, marketplaces, enabledPlugins), so installing into one project can never break another.

Keeping the whole clone (amendment 19) is a deliberate safety net: the manifest is a map over the copy, its from paths point straight at the plugin's own layout, so a scattered support file the closure walk happens to miss is recoverable from the kept copy rather than lost. A strip-repo.nu pass trims the obvious bloat – build output, installed deps, media, CI, tests, .git – while keeping readmes, docs, and anything a human wants for review, and it never strips a file the manifest lists.

The model is plugin-shaped and the simpler cases fall out of it for free – a bank entry carrying only a skill is the standalone-skill case, one carrying only an MCP block is the standalone-MCP case, nothing special-cases them.

In Practice ​

The flow splits into two halves that never mix: fetch and extract is reasoning work done once, install and update are pure file work done forever after.

Vendor a plugin once. Point the vendor flow at a source:

/vendor github:owner/repo

It clones to scratch, copies the whole clone into the bank entry, and fans a plugin-extractor subagent over it. An agent is there for one reason – a plugin's parts are often scattered, a hook can shell into a scripts/ file no known-folder scan would ever reach, and missing it breaks the plugin in the target project. The extractor computes the real component set plus the full dependency closure and writes the manifest, an install list whose from paths point at the repo's own layout; it copies nothing, the full copy is already in place. A strip-repo.nu pass then trims the bloat off that copy (never touching a file the manifest lists), and a plugin-verifier pass installs the entry into a temp project through the real installer and checks the result, and only that flips verified to true.

Install it anywhere, for free. From then on it costs no tokens. Discovery reads plugins/*/manifest.json and every banked plugin shows in the picker under the external accordion, beside the built-in parts:

harness install                            # tick it in the picker
harness install --parts ext:name --yes     # or headless, by its namespaced name

Install copies the picked components in prefixed, rewrites the self-reference tokens to the plugin's owned dir, and merges the hook block into settings.json and the MCP block into .mcp.json, both namespaced:

  + ext:name
  wired 1 hook into .claude\settings.json
  wired 1 mcp server into .mcp.json
done, 2 items into <project>\.claude

Each mcp server lands keyed <plugin>-<server>, unless the entry IS its own server, in which case the key collapses to the bare server name – nushell-mcp bringing nushell wires as nushell, not nushell-mcp-nushell, so the tool name an agent sees (mcp__nushell__evaluate) matches what the docs and stored lessons already call it. The prefix still stands wherever it buys real collision safety, a second server off the same plugin or an unrelated name.

An unverified plugin installs with a warning to review it first, and external dependencies (an npm package, a system binary) are listed, never fetched – they are your prerequisites, a missing one is a known gap not a silent break.

Refresh after a re-vendor. A vendored plugin updates anywhere recorded parts update – it is a registry row like any other:

harness install -U            # with everything else recorded here
harness installs              # per project, enter or u on its row
harness projects              # refresh a whole project in place
harness doctor --fix          # as a stale finding

The refresh is not a plain copy. Every recorded-picks update routes an ext: pick back through the extern engine, so the token rewrite re-runs and the hook and MCP blocks re-merge – a plain copy would land live ${CLAUDE_PLUGIN_ROOT} tokens. A component that left the manifest on a re-vendor simply falls out of the pick, mirroring how a built-in sheds a copy that left its definition. harness diff deliberately skips an extern part: its installed files are rewritten on install, so a byte compare against the bank would always read changed – the registry digest is its truth.

Remove clean. Remove is the manifest read backwards – delete the prefixed files and the owned dir, strip the namespaced hook and MCP keys:

harness installs --remove ext:name --yes

A plugin whose bank entry has since vanished still removes, off the dests the registry recorded – it just can't update any more, and doctor reports it as having left the bank. Its mcp key isn't known any more either, so that remove path sweeps every <plugin>- prefixed key plus the collapsed bare alias rather than reading an exact list off a manifest that may no longer exist.

An example outcome. You vendor a plugin carrying a skill and a support script, tick it in a project's picker, and both land prefixed with its hook wired. The source re-vendors a week later, harness projects shows that project a yellow stale, one enter refreshes it in place – new files, tokens rewritten, merges re-run – and the row reads current again.

The Manifest ​

One manifest.json per bank entry, written by the extractor, read by everything else. It carries the component list, the hook and MCP blocks verbatim, the self-reference tokens to rewrite, the external dependencies install won't fetch, and an unresolved list – warn is review-this, block is this-part-cannot-be-vendored (a bin/ dir or an LSP config has no standalone .claude/ equivalent).

A bank entry doesn't need any components at all – excalidraw-mcp's components list is empty, its whole module is a remote http url sitting in the mcp block, the standalone-MCP case the model above already covers for free. Its entry name is also its server name, so it wires under the collapsed bare key, excalidraw, the same rule nushell-mcp follows.

Components land prefixed so nothing collides and Claude Code still finds them:

TypeLands at
skill.claude/skills/<plugin>-<name>/
command.claude/commands/<plugin>-<name>.md
agent.claude/agents/<plugin>-<name>.md
support.claude/<plugin>/<path> – the owned dir

Invokables are prefixed individually because Claude Code discovers skills as immediate subdirs and commands as flat files – a wrapping folder would never be found. Support files go under the one owned dir it never scans, which keeps them namespaced and makes remove a single delete. That owned dir is also what every ${CLAUDE_PLUGIN_ROOT} token rewrites to – the honest analog of what the token means, the plugin's own root.

Each component's from is the path as it sits in the kept copy – the repo's own layout, skills/review or scripts/lint.sh, with no relocation (amendment 19). For a support file the install value mirrors that path so its internal structure survives under the owned dir and a ./lib/rules.sh source still resolves. The install engines never had to change for this: they only ever read from, so an original-layout path resolves through exactly the same copy as a normalized one did.

The bank's contents under plugins/ are vendored third-party code – exempt from finn-style, never reformatted, not ours. The one dir the harness adds to an entry is .vendor-stash/, where the strip pass parks lockfiles so a rebuild can restore them.

Key Files ​

The Vendor Flow ​

skills/vendor/SKILL.md ​

The overseer – the /vendor procedure, clone then extract then verify, and the bank-entry contract the other pieces follow.

agents/plugin-extractor.md ​

The closure walker – reads the kept copy, computes the real component set and every scattered file the components reach, and writes the manifest.json (the install list, from in the repo's own layout). It copies nothing – the overseer already placed the full copy, so a missed file is recoverable, not lost.

strip-repo.nu ​

The strip pass – trims the obvious bloat off the kept copy (build output, deps, media, CI, tests, .git), moves lockfiles into .vendor-stash/, and keeps readmes, docs, and examples. It reads the manifest first so it never removes a file the install list references, even one sitting inside a stripped dir. The category lists are plain data at the top of the script, tunable.

agents/plugin-verifier.md ​

The proof – installs a bank entry into a temp project through the real installer and checks each component, hook, and rewrite landed; a fail names the defect instead of shipping it.

The Install Engines ​

installer/src/extern/extern.ts ​

Discovery – discoverExtern walks extern/{plugins,skills,commands,agents,hooks,mcps}/*/manifest.json and synthesizes a namespaced ext:<name> tree part per plugin, one leaf per component with real from and to paths. That one shape change is why the picker renders it, hashPart stamps it, and validate collision-checks it without knowing it came from disk.

installer/src/extern/extern-install.ts ​

Install and remove – runExternInstall copies through the shared engine then rewrites the tokens and merges the hook and MCP blocks; runExternRemove is the same backwards, and it still holds the manifest so it passes unmergeExternMcp the entry's own server names exactly (plus their pre-collapse <plugin>-<server> shape, so an install made before the 2026-09-05 key collapse doesn't strand its key). removeExternByName has no manifest – the bank entry may be gone – so it handles a project's recorded dests alone and falls back to a same-name sweep on the mcp side.

installer/src/engines/refresh.ts ​

The shared update – runRefresh, the one extern-aware refresh over recorded picks. Every viewer update comes through it, so a built-in gets a plain refresh while an extern pick re-runs its rewrite and merges, and neither path can drift from the other.

installer/src/engines/merge.ts ​

The settings merges – applyExternHooks / applyExternMcp land the namespaced blocks idempotently with a backup first. applyExternMcp keys each server through externMcpKey, which collapses the <plugin>-<server> prefix to the bare server name when the entry IS its own server, and keeps the prefix wherever it buys collision safety, a second server or an unrelated name. mcpAlias (dropping the mcp token off a bank name, nushell-mcp -> nushell) is the one place that decision is made, and extern-wired.ts's serverName reads the same helper, so the name an add derives and the key an install writes can't drift apart. The unmerge twin is exact only on the manifest-carrying path – unmergeExternMcp takes the caller's own server list and strips precisely those keys – without one it falls back to a sweep of every <plugin>- key plus the collapsed alias, the one heuristic in the pack. A malformed settings file throws rather than getting clobbered.

Connects to ​

  • Folds into the installer everywhere – the picker's external accordion, the shared registry keyed ext:<name>, the same content digest for stale detection, and the reconstruction family in registry.ts takes the discovered parts as an extra so an ext: row resolves beside the built-ins.
  • Merges into the same settings.json the hooks module wires – an extern plugin's hooks are namespaced by its owned-dir path so a remove strips exactly its own entries.
  • Managed through harness extern (items 124–127) – browse the type-sorted bank with each module's install-status in this project, download a new module by link or name (--add / d, the shallow extract), update-check against each recorded ref (--check / u), and drill into what a module holds. The /vendor deep closure walk is the opt-in handoff behind it.
  • Driven by plan-system amendment 7 (items 83 to 90, 97) and revised by amendment 19 (item 123, the full-copy bank) – the bank contract, the extract and verify agents, the strip pass, discovery, install, remove, and the extern-aware update.