Claude-Vault

April 30, 2026 · View on GitHub

Meta-plugin for per-project activation of dormant plugins and MCP servers from a personal vault.

Mitigates the user-level eager skill-description loading problem (see Claude-Vault-Idea for the full write-up): plugins enabled at user level inject all their skill descriptions into every session's system prompt. With many plugins installed, that adds up. The vault pattern keeps everything installed-but-dormant and activates only what each project needs, by editing project-level .claude/settings.json and .mcp.json.

This is a workaround for a current Claude Code limitation, not a permanent design.

Status

Functional: list-vault, list-active, activate-plugin, activate-mcp, deactivate-plugin, deactivate-mcp, activate-bundle, update-vault, vault-search. Stubs: setup-workspace, bundle-create.

Progressive discovery

The discovery problem with dormant plugins: once skills are off, you stop knowing they exist. Claude-Vault solves this with a single always-on skill, vault-search, that greps a flat skill-index across every dormant plugin in the vault. Ask "is there something for trimming silence?" — vault-search finds the candidate skill, names its parent plugin, and offers to activate it. The full skill descriptions never enter context until you opt in.

The index is generated by update-vault from the inventory's per-plugin skills metadata (or by best-effort scanning of installed SKILL.md files when metadata is absent). Format is one pipe-delimited line per skill — see skills/_shared/skill-index.md.

Install

claude plugin install Claude-Vault

(Or clone and add via your local marketplace.)

Then create the vault inventory file (see Vault inventory format below). Resolve the path as:

$CLAUDE_USER_DATA/claude-vault/inventory.json if CLAUDE_USER_DATA is set
else $XDG_DATA_HOME/claude-plugins/claude-vault/inventory.json if XDG_DATA_HOME is set
else ~/.local/share/claude-plugins/claude-vault/inventory.json

(Plugin data must not live under ~/.claude/ — that's Claude Code's own config surface and gets clobbered on plugin updates.)

Skills

Skill	Status	What it does
`vault-search`	✅	Find a dormant skill or plugin by keyword (progressive discovery)
`list-vault`	✅	Enumerate plugins, MCP servers, and bundles in the inventory
`list-active`	✅	Show what's currently enabled in the current project
`activate-plugin`	✅	Enable a vault plugin in the current project's `.claude/settings.json`
`activate-mcp`	✅	Add a vault MCP server to the current project's `.mcp.json`
`activate-bundle`	✅	Apply a named bundle (plugins + MCP servers) in one shot
`deactivate-plugin`	✅	Disable a plugin in the current project (symmetric to `activate-plugin`)
`deactivate-mcp`	✅	Unmount an MCP server from the current project
`update-vault`	✅	Pull plugin updates and regenerate the skill-index for `vault-search`
`setup-workspace`	🚧	Bootstrap a new project with a chosen template + tools
`bundle-create`	🚧	Save the current project's tool set as a reusable bundle

Vault inventory format

Inventory file (resolved per the path rules above):

{
  "plugins": [
    {
      "name": "podcast-production",
      "marketplace": "danielrosehill",
      "description": "Tools for podcast editing and publishing",
      "tags": ["podcast", "audio"],
      "skills": [
        { "name": "trim-silence", "description": "Trim leading and trailing silence from an audio file" },
        { "name": "denoise", "description": "Remove background noise from an audio recording" }
      ]
    }
  ],
  "mcpServers": [
    {
      "name": "greeninvoice",
      "description": "Israeli invoicing API",
      "config": {
        "command": "npx",
        "args": ["-y", "@greeninvoice/mcp-server"],
        "env": { "GREENINVOICE_API_KEY": "${GREENINVOICE_API_KEY}" }
      },
      "tags": ["finance", "israel"]
    }
  ],
  "bundles": [
    {
      "name": "podcast",
      "description": "Full podcast production stack",
      "plugins": ["podcast-production"],
      "mcpServers": []
    }
  ]
}

Plugins must already be installed on your system (cloned from a marketplace). The vault is an activation layer, not an installer — it does not fetch plugins.

The optional skills array per plugin entry is what powers vault-search. It's optional: if absent, update-vault will best-effort scan the plugin's installed SKILL.md files. Carrying the metadata in the inventory is faster and more reliable.

Workflow

One time — populate inventory.json with the plugins you've installed, then run update-vault to generate the skill-index.
Per project — when starting work in a repo, either activate-bundle <name> (if you have a bundle for this kind of project) or describe the task and let vault-search surface candidates, then activate-plugin the ones you want.
Restart Claude Code in the project for activations to take effect.
When done — deactivate-plugin / deactivate-mcp if you want a clean slate, or just leave them — they're already project-scoped.

License

MIT