Plugin Engine

Plugins bundle everything — commands, agents, hooks, and servers — into one installable package. They’re how Claude Code’s ecosystem grows beyond the built-in feature set.

4 Extension Points

Extension Point	What It Provides	Scoped To
Commands	Slash commands from markdown files	Plugin namespace
Agents	Custom AI agents with system prompts and tool subsets	Plugin namespace
Hooks	Shell commands triggered on 26 lifecycle events	Session-wide
Servers	MCP servers (external tools) + LSP servers (language intelligence)	Session-wide

A single plugin can use all four. A plugin that adds TypeScript intelligence might ship: an LSP server for type errors, a /ts:review command, a ts-refactor agent, and a PostToolUse hook that runs tsc --noEmit after every file write.

26 Lifecycle Hook Events

Category	Events
Tool lifecycle	`PreToolUse`, `PostToolUse`, `PostToolUseFailure`
Permission	`PermissionDenied`, `PermissionRequest`
Session	`SessionStart`, `SessionEnd`, `Setup`
Agent lifecycle	`SubagentStart`, `SubagentStop`, `TeammateIdle`
Task	`TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`
Context	`PreCompact`, `PostCompact`, `Notification`
Filesystem	`FileChanged`, `CwdChanged`, `WorktreeCreate`, `WorktreeRemove`
UI / Config	`Elicitation`, `ElicitationResult`, `ConfigChange`, `InstructionsLoaded`, `UserPromptSubmit`

Each hook receives a JSON payload describing the event. The hook is a shell command that reads from stdin or environment variables and optionally writes back to stdout to inject content into the conversation.

The Power Pair: PreToolUse + PostToolUse

PreToolUse can block tool execution by returning a deny response. PostToolUse triggers follow-up actions after execution completes.

Example: Auto-lint workflow

1. Agent decides to write a file
2. PreToolUse fires → check if file is in src/ → allow
3. FileWrite executes
4. PostToolUse fires → run eslint on the written file
5. ESLint output injected into conversation
6. Agent reads lint errors, fixes them
7. Cycle repeats until lint passes

Result: agent self-corrects lint errors without user prompting

Another use: PreToolUse on Bash can block dangerous patterns:

if command matches "rm -rf /" or "DROP TABLE":
    return deny("Blocked: destructive command requires explicit approval")

This runs at the hook layer, before the tool executes — not inside the agent prompt.

32 Official Plugins

Category	Plugins
LSP (12)	TypeScript, Rust, Python, Go, C/C++, Ruby, Swift, PHP, Kotlin, Lua, Java, C#
Workflow (10)	feature-dev, code-review, pr-review-toolkit, commit-commands, code-simplifier, security-guidance, dependency-updater, changelog-writer, test-generator, documentation-sync
Meta (6)	plugin-dev, skill-creator, mcp-server-dev, agent-sdk-dev, claude-code-setup, claude-md-management
Output (4)	explanatory-output-style, learning-output-style, example-plugin, frontend-design

LSP plugins provide real-time language intelligence: type errors, go-to-definition, rename symbol, and diagnostics — all without leaving the Claude Code session.

Security Sandbox

Plugin agents have restricted permissions compared to manually defined agents:

flowchart LR subgraph INSTALL["At install time (trusted)"] PM[Plugin manifest] --> ALLOWED["Allowed:\nPlugin-level hooks\nPlugin-level MCP servers\nPlugin-level commands"] end subgraph RUNTIME["At runtime (sandboxed)"] PA[Plugin agent definition] --> BLOCKED["BLOCKED per-agent:\npermissionMode elevation\nhooks override\nmcpServers override"] end INSTALL -->|"Sandbox enforced"| RUNTIME

Why? A plugin agent that could set permissionMode: bypassPermissions would gain unrestricted file access beyond what the user approved at install time. Plugin-level settings are reviewed at install. Per-agent escalation at runtime bypasses that review — so it’s blocked unconditionally.

Enterprise policies can whitelist or blacklist entire marketplaces. An organization can restrict installs to their internal registry only.

Reconciliation-Based Install

Plugin installation works like Kubernetes resource reconciliation — not like a traditional package manager:

Traditional (download-then-done):
  install plugin → done, state diverges over time

Reconciliation (continuous):
  Desired state: settings.json plugins list
  Actual state:  disk contents
  Reconciler:    diff → install missing → update changed → remove deleted
  Triggers:      startup + /reload-plugins command

flowchart TD DESIRED["Desired state\nsettings.json"] --> DIFF{Diff} ACTUAL["Actual state\ndisk"] --> DIFF DIFF -->|"Missing"| INSTALL[Install] DIFF -->|"Source changed"| UPDATE[Update] DIFF -->|"Removed from settings"| REMOVE[Remove] DIFF -->|"Match"| NOOP[No-op] INSTALL & UPDATE & REMOVE --> RELOAD[Hot reload\n/reload-plugins]

Reconciliation runs in the background at startup — non-blocking. Trigger it manually with /reload-plugins after editing settings.json. Your settings file is always the source of truth; disk state catches up to it.

Choosing the Right Extension Point

I want to…	Use
Add a shortcut command for my team	Command
Create a specialized AI with different behavior	Agent
Auto-run checks after file changes	Hook (`PostToolUse`)
Block dangerous operations	Hook (`PreToolUse`)
Connect to an external API or database	MCP Server
Add language-aware intelligence	LSP Server

Why This Matters to You

Full hook event catalog → 26 events cover the entire session lifecycle; if something happens in Claude Code, there’s a hook for it
Why plugin agents have restricted permissions → security sandbox prevents runtime escalation beyond install-time trust; this is by design
How to pick the right extension point → commands for user shortcuts, agents for specialized AI behavior, hooks for automation triggers, servers for external tool connectivity
What official plugins exist → 32 across 4 categories; LSP plugins are the fastest way to add language intelligence
How plugin installation works → reconciliation means your settings.json is always the source of truth; disk state catches up automatically

See also: Skill Engine — Multi-Agent System — Permission Pipeline