The Claude Code Plugin System

The plugin system is the extensibility backbone of Claude Code. It lets third-party authors (and Anthropic itself) ship slash commands, MCP servers, AI agents, lifecycle hooks, LSP integrations, skills, and output styles — all from a Git repository or npm package — without touching the core binary.

There are five conceptual layers you need to understand:

The diagram traces a full plugin journey from user intent to active capability:

A marketplace is a catalog — a marketplace.json file that lists plugins. Claude Code supports six source types for fetching that catalog:

Reserved name protection

The schema enforces two layers of impersonation defense. The BLOCKED_OFFICIAL_NAME_PATTERN regex blocks names like official-claude-plugins or anthropic-marketplace-v2. For reserved names in the allowlist (like claude-plugins-official), the source org must be anthropics/ on GitHub.

// schemas.ts — blocked pattern for impersonation attempts
export const BLOCKED_OFFICIAL_NAME_PATTERN =
  /(?:official[^a-z0-9]*(anthropic|claude)|(?:anthropic|claude)[^a-z0-9]*official|^(?:anthropic|claude)[^a-z0-9]*(marketplace|plugins|official))/i

// Non-ASCII blocks homograph attacks (Cyrillic 'а' ≠ Latin 'a')
const NON_ASCII_PATTERN = /[^\u0020-\u007E]/

export function validateOfficialNameSource(name, source): string | null {
  // Reserved name? Must come from github.com/anthropics/
  if (source.source === 'github') {
    const repo = source.repo || ''
    if (!repo.toLowerCase().startsWith(`anthropics/`)) {
      return `The name '${name}' is reserved for official Anthropic marketplaces.`
    }
  }
  return null
}

Every plugin optionally ships a plugin.json at its root. Claude Code parses this with a strict Zod schema. Unknown top-level keys are silently stripped (resilience to future fields); unknown keys inside nested objects like userConfig or channels still fail validation.

{
  "name": "my-plugin",
  "version": "1.2.0",
  "description": "Example plugin showing all capability types",
  "author": { "name": "Acme Corp", "url": "https://acme.example" },
  "license": "MIT",

  // Declare a dependency — bare name inherits this plugin's marketplace
  "dependencies": ["shared-utils"],

  // Commands: directory is auto-scanned + extra file + inline content
  "commands": {
    "hello": { "content": "Say hello to ${CLAUDE_PLUGIN_ROOT}" },
    "deploy": { "source": "./docs/deploy.md", "argumentHint": "[env]" }
  },

  // Hooks: inline or path
  "hooks": "./hooks/extra.json",

  // MCP server via .mcpb bundle (pre-packaged binary)
  "mcpServers": "./server.mcpb",

  // LSP server for TypeScript
  "lspServers": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "extensionToLanguage": { ".ts": "typescript", ".tsx": "typescriptreact" }
    }
  },

  // User-configurable values (prompted at enable time)
  "userConfig": {
    "API_KEY": {
      "type": "string",
      "title": "API Key",
      "description": "Your service API key",
      "sensitive": true,   // → stored in keychain, not settings.json
      "required": true
    }
  }
}

Plugins are installed into an immutable content-addressed cache under ~/.claude/plugins/cache/. The path structure is:

# Path format
~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/

# Example
~/.claude/plugins/cache/claude-plugins-official/sql-helper/1.3.2/
~/.claude/plugins/cache/acme-mkt/deploy-tool/a3f8c1d94b12/
~/.claude/plugins/cache/acme-mkt/monorepo-plugin/a3f8c1d94b12-e5a7c3f1/
                                                          ^^ path hash for git-subdir

Version priority order

The version string is calculated in pluginVersioning.ts with this priority:

1. plugin.json version field — explicit semver, highest authority
2. Provided version from marketplace entry (e.g., pinned in marketplace.json)
3. Pre-resolved git SHA — captured before the clone is discarded (git-subdir case)
4. Git commit SHA read from .git/HEAD in the install path (first 12 chars)
5. 'unknown' as last resort — still creates a valid cache path

Seed cache fallback

Enterprise deployments can pre-populate a read-only seed directory (set via CLAUDE_CODE_PLUGIN_SEED_DIR). On install, the loader probes seeds before performing any network fetch. This enables zero-network-on-first-run scenarios.

Zip cache mode

When CLAUDE_CODE_PLUGIN_USE_ZIP_CACHE=1 is set (headless/container deployments), plugins are stored as .zip files instead of directories on a mounted Filestore. At session start they are extracted to a claude-plugin-session-{hex}/ temp dir and cleaned up on exit. Unix execute bits are preserved via the ZIP central directory's external_attr field — critical for hooks and scripts that need +x.

// pluginLoader.ts
export function getVersionedCachePathIn(
  baseDir: string,
  pluginId: string,
  version: string,
): string {
  const { name: pluginName, marketplace } = parsePluginIdentifier(pluginId)
  // Sanitize each segment to prevent path traversal
  const sanitizedMarketplace = (marketplace || 'unknown').replace(/[^a-zA-Z0-9\-_]/g, '-')
  const sanitizedPlugin    = (pluginName    || pluginId).replace(/[^a-zA-Z0-9\-_]/g, '-')
  const sanitizedVersion   = version.replace(/[^a-zA-Z0-9\-_.]/g, '-')
  return join(baseDir, 'cache', sanitizedMarketplace, sanitizedPlugin, sanitizedVersion)
}

// pluginVersioning.ts — git-subdir path hash
const normPath = source.path
  .replace(/\\/g, '/')    // backslash → forward slash
  .replace(/^\.\//, '')    // strip leading ./
  .replace(/\/+$/, '')     // strip trailing /
const pathHash = createHash('sha256').update(normPath).digest('hex').substring(0, 8)
const v = `${shortSha}-${pathHash}`

The plugin system has two dependency resolution passes with distinct semantics, implemented in dependencyResolver.ts:

Install-time: resolveDependencyClosure()

A recursive DFS walk that computes the full transitive closure of plugins to install. It enforces three rules:

• Cycle detection — if a plugin appears on the current DFS stack, return { reason: 'cycle' }
• Cross-marketplace block — plugin A from marketplace X cannot auto-install plugin B from marketplace Y (unless Y is on X's allowCrossMarketplaceDependenciesOn allowlist)
• Already-enabled skip — deps already in settings are skipped to avoid clobbering version pins, but the root is never skipped (handles "cache cleared but still in settings" case)

export async function resolveDependencyClosure(
  rootId: PluginId,
  lookup: (id: PluginId) => Promise<DependencyLookupResult | null>,
  alreadyEnabled: ReadonlySet<PluginId>,
  allowedCrossMarketplaces: ReadonlySet<string> = new Set(),
): Promise<ResolutionResult> {
  const closure: PluginId[] = []
  const visited = new Set<PluginId>()
  const stack: PluginId[] = []  // DFS stack for cycle detection

  async function walk(id, requiredBy) {
    // Skip already-enabled DEPS (not root) to avoid stomping version pins
    if (id !== rootId && alreadyEnabled.has(id)) return null

    // Cross-marketplace security gate
    const idMkt = parsePluginIdentifier(id).marketplace
    if (idMkt !== rootMarketplace && !allowedCrossMarketplaces.has(idMkt)) {
      return { ok: false, reason: 'cross-marketplace', dependency: id, requiredBy }
    }

    if (stack.includes(id)) return { ok: false, reason: 'cycle', chain: [...stack, id] }
    if (visited.has(id)) return null
    visited.add(id)

    const entry = await lookup(id)
    if (!entry) return { ok: false, reason: 'not-found', missing: id, requiredBy }

    stack.push(id)
    for (const rawDep of entry.dependencies ?? []) {
      const dep = qualifyDependency(rawDep, id)  // inherit marketplace if bare name
      const err = await walk(dep, id)
      if (err) return err
    }
    stack.pop()
    closure.push(id)   // post-order: deps come before dependents
    return null
  }

  const err = await walk(rootId, rootId)
  if (err) return err
  return { ok: true, closure }
}

Load-time: verifyAndDemote()

Run on every session start from the cache-only loaded set. It is a fixed-point loop: demoting plugin A (because its dep is missing) may uncover that plugin B depends on A, so B must also be demoted. The loop repeats until no changes occur.

Commands and skills

Commands live in commands/*.md. Each file becomes a slash command named /plugin-name:command-name. Subdirectories create namespaces: commands/ci/build.md → /my-plugin:ci:build.

Skills are directories containing SKILL.md. When Claude Code finds SKILL.md in a subdirectory of skills/, it registers the parent directory name as the skill name and injects ${CLAUDE_SKILL_DIR} so the skill can reference its own support files.

Hooks

Plugin hooks are converted to PluginHookMatcher[] objects and registered alongside the global hook config. Every hook event is supported:

// All 20+ hook events a plugin can subscribe to:
PreToolUse | PostToolUse | PostToolUseFailure | PermissionDenied
Notification | UserPromptSubmit | SessionStart | SessionEnd | Stop | StopFailure
SubagentStart | SubagentStop | PreCompact | PostCompact
PermissionRequest | Setup | TeammateIdle
TaskCreated | TaskCompleted | Elicitation | ElicitationResult
ConfigChange | WorktreeCreate | WorktreeRemove
InstructionsLoaded | CwdChanged | FileChanged

Policy blocking (managed-settings.json)

Enterprise admins can force-disable any plugin by setting enabledPlugins["name@marketplace"] = false in managed-settings.json. The isPluginBlockedByPolicy() check runs at the install chokepoint, the enable operation, and in the UI — a single source of truth that cannot be overridden by user or project settings.

Delisting and auto-uninstall

When a marketplace sets forceRemoveDeletedPlugins: true, Claude Code compares installed_plugins.json against the current marketplace manifest at startup. Plugins no longer listed are automatically uninstalled from all user-controlled scopes and recorded in a flagged-plugins file to prevent re-install loops.

Installation scopes

Plugins can be installed at four scopes. Only the first three are user-installable:

// dependencyResolver.ts
export function findReverseDependents(
  pluginId: PluginId,
  plugins: readonly LoadedPlugin[],
): string[] {
  const { name: targetName } = parsePluginIdentifier(pluginId)
  return plugins
    .filter(p =>
      p.enabled &&
      p.source !== pluginId &&
      (p.manifest.dependencies ?? []).some(d => {
        const qualified = qualifyDependency(d, p.source)
        // Bare dep from @inline plugin: match by name only
        return parsePluginIdentifier(qualified).marketplace
          ? qualified === pluginId
          : qualified === targetName
      }),
    )
    .map(p => p.name)
}
// Result shown as: "warning: required by plugin-a, plugin-b"

At startup, autoUpdateMarketplacesAndPluginsInBackground() runs silently without blocking the REPL. The flow has three phases:

1. Determine which marketplaces have autoUpdate: true — official marketplaces default to true, third-party default to false
2. Run refreshMarketplace() (git pull / re-fetch) for each auto-update marketplace
3. Call updatePluginOp() for each installed plugin from those marketplaces

Updates are non-in-place: the new version is cached at a new versioned path but the running session continues using the old path. The REPL is notified via onPluginsAutoUpdated() and shows a restart prompt.