Skip to content

Claude Code Plugin

Nuzo's Claude Code package is an official-path wrapper around the Nuzo MCP server.

It should make the same Nuzo memory tools available in Claude Code without adding Claude-specific memory behavior.

Claude Code is one host package, not the product boundary. Codex and future MCP-compatible agent CLIs should use the same MCP server and core behavior.

Package

Development source:

packages/claude-code-plugin/
├── .claude-plugin/plugin.json
├── .mcp.json
├── skills/
│   └── nuzo-memory/
│       └── SKILL.md
└── README.md

Generated release artifact:

build/plugins/claude-code/nuzo/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── nuzo-memory/
│       └── SKILL.md
├── .mcp.json
└── LICENSE

Generate and validate it with:

npm run package:plugins

Current Scope

The package currently provides:

  • Claude Code plugin metadata;
  • MCP server defaults for the nuzo MCP server;
  • a Claude Code skill that tells the host how to use Nuzo safely.

It does not provide:

  • a separate memory engine;
  • Claude-specific storage;
  • lifecycle hooks;
  • an installer script;
  • native Claude Code memory migration.

Official Claude Code Shape

Claude Code plugins are installable packages that can bundle skills, agents, hooks, MCP servers, LSP servers, background monitors, default settings, and executables.

For Nuzo, the useful parts are:

  • .claude-plugin/plugin.json for plugin metadata;
  • .mcp.json at the plugin root for MCP server configuration;
  • skills/ at the plugin root for Claude Code-specific usage guidance.

Only plugin.json belongs inside .claude-plugin/. Skills, hooks, agents, MCP config, and other components should stay at the plugin root.

Nuzo keeps the plugin identifier nuzo and the human display name Nuzo.

MCP Server

The plugin points Claude Code at the Nuzo MCP server:

{
  "mcpServers": {
    "nuzo": {
      "command": "node",
      "args": [
        "${CLAUDE_PLUGIN_ROOT}/../mcp-server/dist/index.js"
      ]
    }
  }
}

This is the monorepo development default.

The generated release artifact instead uses:

{
  "mcpServers": {
    "nuzo": {
      "command": "npx",
      "args": ["--yes", "@nuzo/mcp-server@0.1.0"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

0.1.0 is illustrative. Packaging pins the actual plugin version. This keeps the artifact portable across supported platforms while allowing npm to install the correct native SQLite build.

Build the monorepo before testing the MCP path:

npm run build
test -f packages/mcp-server/dist/index.js

Claude Code sets plugin-specific environment variables for plugin-provided MCP servers. Nuzo uses ${CLAUDE_PLUGIN_ROOT} so the plugin resolves the MCP server relative to the installed plugin package.

Development Install Flow

This flow validates the monorepo source package.

  1. Build the monorepo:
npm run build
  1. Validate the Nuzo Claude Code plugin metadata:
npm run check -w @nuzo/claude-code-plugin
  1. If Claude Code is installed locally, validate with the host CLI:
claude plugin validate packages/claude-code-plugin
  1. For source-level local development, load the plugin directory directly:
claude --plugin-dir packages/claude-code-plugin
  1. After changing plugin components such as .mcp.json, run:
/reload-plugins

  1. Confirm the nuzo MCP server and the nuzo-memory skill are visible in Claude Code before relying on the plugin.

  2. To validate the release layout, generate it and run the host validator:

npm run package:plugins
claude plugin validate build/plugins/claude-code/nuzo --strict

The generated config becomes runnable only after its matching @nuzo/mcp-server version is published.

Marketplace Install Direction

For normal sharing, Claude Code plugins should be distributed through a marketplace and installed with:

claude plugin install nuzo@<marketplace-name>

Scopes should be selected intentionally:

  • user scope for personal installs;
  • project scope for team-shared repository setup;
  • local scope for machine-specific testing.

Nuzo should not add repository-level marketplace settings until the matching MCP package publication and update behavior are validated.

Direct MCP Fallback

For debugging the MCP server without plugin packaging, configure Claude Code directly against the built server:

claude mcp add --transport stdio nuzo -- node /absolute/path/to/nuzo/packages/mcp-server/dist/index.js

Use this only to isolate MCP behavior. Plugin validation should still go through the package in packages/claude-code-plugin.

Validation

Run:

npm run check -w @nuzo/claude-code-plugin

The validator checks:

  • .claude-plugin/plugin.json exists;
  • the plugin name remains nuzo;
  • the optional display name remains Nuzo;
  • the license remains Apache-2.0;
  • .mcp.json defines an MCP server named nuzo;
  • the nuzo MCP server uses node;
  • the development server resolves through ${CLAUDE_PLUGIN_ROOT};
  • host-specific skill files exist when referenced.

Release validation additionally checks:

  • the MCP server runs through npx;
  • @nuzo/mcp-server is pinned to the plugin version;
  • cwd resolves through ${CLAUDE_PLUGIN_ROOT};
  • no sibling monorepo path remains.

If the claude CLI is installed, run the host validator too:

claude plugin validate packages/claude-code-plugin

Boundary

Claude Code plugin files are packaging files only.

Memory lifecycle, policy checks, recall ranking, import/export, and storage belong in packages/core. Tool schemas and host-facing tool behavior belong in packages/mcp-server and docs/spec/tools.md.

Hooks

Claude Code supports hooks, but Nuzo should not add automatic recall or capture hooks until the policy is documented.

The hook policy is defined in docs/operations/lifecycle-hooks.md.

The capture suggestion contract is defined in docs/spec/capture-suggestions.md.

Before adding host-specific hooks, document:

  • when recall is triggered;
  • when capture is suggested;
  • which memories require user confirmation;
  • how secrets and transient logs are filtered;
  • how users disable the behavior.

The current safe prototype is the MCP tool memory.recall_hook. It gives Claude Code a read-only recall entrypoint without enabling automatic capture.

Portability

Export/import remains a Nuzo feature:

Claude Code + Nuzo plugin
  -> memory.export
  -> nuzo-memory-export JSON
  -> memory.import
  -> Codex + Nuzo plugin

This covers memories created and managed through Nuzo. It does not promise access to Claude Code's private native memory unless Claude Code exposes an official API or export format.

Source References

  • Claude Code docs, Create plugins: plugin structure, --plugin-dir, /reload-plugins, and marketplace direction.
  • Claude Code docs, Plugins reference: manifest schema, component locations, and plugin CLI commands.
  • Claude Code docs, MCP: stdio MCP setup and plugin-provided MCP variable behavior.
  • Claude Code docs, Settings: plugin enablement, scopes, and marketplace configuration.