Claude Code — Extension Architecture

📄

CLAUDE.md Files Native

Persistent instructions loaded into every conversation. The primary way to give Claude always-on context about your project, preferences, and rules.

*"The instructions that are always there"*

Precedence (highest → lowest): /etc/claude-code/CLAUDE.md ← managed policy ./CLAUDE.md ← project (committed) ./.claude/rules/*.md ← modular rules ~/.claude/CLAUDE.md ← personal global ./CLAUDE.local.md ← personal project ~/.claude/projects/*/memory/ ← auto-memory

Key features

Feature	How
Import other files	`@path/to/import` syntax (max depth 5)
Path-specific rules	YAML frontmatter with `paths:` glob
Additive loading	All levels contribute simultaneously
Child dirs	Load on-demand when files accessed

Put team conventions in ./CLAUDE.md (committed), personal prefs in CLAUDE.local.md

Use .claude/rules/*.md for modular, topic-specific rules

Don't put secrets or API keys in CLAUDE.md — it's loaded into context

⚡

Skills Native

Markdown instruction packages with optional workflows, tools, and slash commands. Auto-invocable by intent matching or user-invocable via /name.

*"Teach Claude a new specialty"*

skill-name/ SKILL.md ← YAML frontmatter + instructions Workflows/ ← step-by-step procedures Tools/ ← CLI tools (TypeScript) *.md ← reference context files

Frontmatter options

Field	Purpose
`name`	Slash command name
`description`	Intent matching for auto-invocation
`allowed-tools`	Skip permission prompts
`context: fork`	Run in isolated subagent
`model`	Override model when active
`hooks`	Skill-scoped lifecycle hooks
`disable-model-invocation`	Only user can trigger

Legacy: Slash Commands

Still supported but skills are preferred: .claude/commands/name.md ← project commands ~/.claude/commands/name.md ← global commands Same YAML frontmatter as skills. If a skill and command share a name, the skill takes precedence.

Write a strong description — Claude uses it for auto-invocation intent matching

Use context: fork for heavy skills to avoid polluting the main context

Don't use legacy .claude/commands/ for new work — skills are the replacement

⚙️

Settings & Config Native

JSON configuration files controlling permissions, hooks, environment, model, MCP, sandbox, UI, and more. Five-level precedence hierarchy.

*"The control plane"*

Precedence (highest → lowest): /etc/.../managed-settings.json ← org policy CLI flags ← session only .claude/settings.local.json ← personal project .claude/settings.json ← shared project ~/.claude/settings.json ← personal global

Key configuration areas

Area	Keys
Permissions	`allow`, `deny`, `ask`, `defaultMode`
Hooks	`hooks` object (event → handler map)
Environment	`env` object (injected into all sessions)
Model	`model`, `availableModels`
MCP	`enableAllProjectMcpServers`
Sandbox	`sandbox.enabled`, network allowlists
Plugins	`enabledPlugins`, marketplaces

Use .claude/settings.local.json for personal prefs that shouldn't be committed

Pre-approve safe commands in allow to reduce permission prompts

Don't put bypassPermissions outside containers — it disables all safety checks

🪝

Hooks Native

Deterministic scripts at lifecycle events. Run outside the AI — no LLM involved (unless type: "prompt" or "agent"). Can block actions (exit 2).

*"Automation that runs every time, no exceptions"*

Event	When	Can Block?
`SessionStart`	Session begins/resumes	No
`UserPromptSubmit`	User sends prompt	No
`PreToolUse`	Before tool executes	Yes
`PostToolUse`	After tool succeeds	No
`Stop`	Claude finishes responding	No
`SubagentStart/Stop`	Agent spawned/finished	No
`Notification`	Attention needed	No
`PreCompact`	Before context compaction	No
`SessionEnd`	Session terminates	No

Hook types

Type	Description
`command`	Shell script (default). stdin=JSON, exit code=action
`prompt`	Single-turn LLM eval (Haiku by default)
`agent`	Multi-turn subagent with tool access

Use PreToolUse hooks to block dangerous commands (exit 2 = block)

Keep hooks fast — they run on every tool call and slow hooks hurt responsiveness

Don't put complex logic in hooks — use type: "agent" for multi-step verification

⌨️

Keyboard & UI Native

Interactive mode with keyboard shortcuts, vim mode, status line, and input modes.

*"The developer-facing surface"*

Shortcut	Action
`Ctrl+C/D`	Cancel / Exit
`Ctrl+G`	Open prompt in editor
`Ctrl+O`	Toggle verbose output
`Ctrl+B`	Background running task
`Ctrl+T`	Toggle task list
`Shift+Tab`	Cycle permission modes
`Alt+P`	Switch model
`/`	Commands & skills
`!`	Bash mode (direct exec)
`@`	File path autocomplete

Use Ctrl+O to debug — verbose mode shows hook output and tool details

Use Shift+Tab to quickly switch to plan mode for exploration

Don't forget Ctrl+B — background long tasks instead of waiting

📊

Status Line Native

The bar below the prompt input. Shows model, permission mode, cost, and can be extended with a custom command that outputs dynamic info (git branch, project state, etc.).

*"Your always-visible dashboard"*

Configure in ~/.claude/settings.json: "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }

How it works

Aspect	Detail
Input	Script receives `CLAUDE_PROJECT_DIR` and other env vars
Output	Script's stdout becomes the status line content
Refresh	Runs on each prompt cycle — keep it fast (<100ms)
Default info	Model name, permission mode, token usage, cost
Custom info	Git branch, test status, build state, project context

Write a fast shell script — it runs on every prompt and slow scripts lag the UI

Show project-relevant context: git branch, active feature, environment

Don't do network calls or heavy computation in the status script

🔌

MCP Servers Native

Model Context Protocol connects Claude to external tools, databases, and APIs. Open standard. Three transport types: HTTP, SSE, stdio.

*"External tool plugins via open protocol"*

Scope hierarchy: ~/.claude.json (project section) ← personal, this project .mcp.json (project root) ← team-shared ~/.claude.json (global section) ← personal, all projects managed-mcp.json ← organization-wide

Key features

Feature	Detail
Tool Search	Lazy-loads tools, reduces context up to 95%
OAuth	Built-in OAuth 2.0 for remote servers
Resources	`@server:protocol://path` mentions
Prompts → Commands	Become `/mcp__server__prompt`
Env vars	`${VAR:-default}` in config

Use .mcp.json in project root for team-shared tool configs

Use ${VAR} in config for secrets — never hardcode API keys

Don't register too many MCP tools — use Tool Search (ENABLE_TOOL_SEARCH=auto) to lazy-load

🛠️

Built-in Tools Native

The core tool set Claude uses automatically. You don't call them directly — Claude picks the right tool based on your request. You guide via prompt shortcuts: @ for files, ! for bash, / for commands.

*"You describe the task, Claude picks the tool"*

Tool	Purpose	You trigger via
`Bash`	Shell commands	`!` prefix or ask for terminal work
`Read`	Files, images, PDFs	`@path` mention or "read this file"
`Edit`	Modify files	"change X to Y in file"
`Write`	Create files	"create a new file with..."
`Glob`	Find files by pattern	"find all *.ts files"
`Grep`	Search content	"search for X in the codebase"
`WebFetch`	Fetch URLs	Paste a URL or "fetch this page"
`WebSearch`	Web search	"search the web for..."
`Task`	Subagents	Claude delegates automatically
`Skill`	Invoke skills	`/skill-name` in prompt

Use @path/to/file to reference files — Claude will read them automatically

Use ! prefix for direct bash execution without Claude's interpretation

Don't micro-manage tool selection — describe what you want, Claude picks the best tool

📦

Plugins Native

Packaging layer that bundles skills, hooks, agents, and MCP servers into a single installable unit. Distributed via marketplaces.

*"npm for Claude Code extensions"*

plugin.json ← manifest skills/ ← bundled skills hooks/hooks.json ← bundled hooks agents/ ← bundled subagents .mcp.json ← bundled MCP servers

Marketplace sources

Source	Example
`github`	GitHub repository
`npm`	npm package
`directory`	Local file path
`url`	Direct URL

Bundle related skills + hooks + agents into one plugin for easy distribution

Don't enable untrusted plugins — they can register hooks and MCP servers

Don't duplicate what a skill can do — plugins are for sharing across teams/projects

🧠

Auto Memory Native

Per-project persistent memory. Claude reads and writes MEMORY.md (first 200 lines loaded at session start). Topic files loaded on demand.

*"Intelligence that compounds across sessions"*

~/.claude/projects/<project>/memory/ MEMORY.md ← auto-loaded (200 lines) debugging.md ← topic file (on demand) patterns.md ← topic file (on demand)

Controls

Env Var	Effect
`CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`	Disable auto-memory
`/memory` command	Open memory files in editor

Keep MEMORY.md under 200 lines — only the first 200 are auto-loaded

Use topic files (debugging.md, patterns.md) for detailed notes

Don't store session-specific state — memory is for stable patterns confirmed across sessions

📝

Session Transcripts Native

Every session saved as JSONL. Enables context recovery, session continuation, and learning extraction. Auto-compaction when context approaches limits.

*"Nothing is ever truly lost"*

~/.claude/projects/<project>/ <session-id>.jsonl ← full transcript <session-id>/subagents/ ← agent transcripts

Use --resume to continue a previous session with full context preserved

Transcripts are great for post-hoc learning extraction and auditing

Don't rely on transcripts for secrets — they're stored as plain-text JSONL

🗜️

Context Compaction Native

When the conversation approaches context limits, Claude automatically summarizes earlier messages. The PreCompact hook fires before this happens.

*"Long conversations that never hit a wall"*

Aspect	Detail
Trigger	Automatic when context window fills (configurable %)
Behavior	Summarizes older messages, preserves recent context
Hook	`PreCompact` fires before — save state or inject reminders
Manual	`Esc Esc` to rewind/summarize on demand
Override	`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` sets trigger %

Use PreCompact hook to inject critical context that must survive compaction

Keep CLAUDE.md instructions concise — they reload after compaction

Don't rely on early conversation details surviving — put stable facts in memory files

🤖

Subagents (Task Tool) Native

Spawn isolated agents for parallel or specialized work. Each runs in its own context window. Cannot nest (no subagent-of-subagent).

*"Divide and conquer with isolated contexts"*

Built-in Type	Model	Purpose
`Explore`	Haiku	Fast, read-only codebase exploration
`Plan`	Inherit	Research during plan mode
`general-purpose`	Inherit	Complex multi-step tasks
`Bash`	Inherit	Terminal commands in separate context

Custom agent frontmatter

Locations: .claude/agents/name.md ← project agents ~/.claude/agents/name.md ← global agents Frontmatter fields: name, description, tools, model permissionMode, maxTurns, skills mcpServers, hooks, memory

Use Explore (Haiku) for cheap, fast codebase searches — save Opus for complex work

Launch independent subagents in parallel — they don't share context

Don't expect nesting — subagents cannot spawn other subagents

👥

Agent Teams Native

Multiple independent Claude Code sessions that communicate via shared task lists and peer-to-peer messaging. Experimental.

*"Self-coordinating agents — no central manager"*

Feature	Subagents	Teams
Context	Own window, returns to caller	Fully independent
Communication	Reports to main only	Peer-to-peer
Coordination	Main manages	Shared task list

Enable

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Use teams for truly independent workstreams that need to coordinate (e.g., frontend + backend)

Don't use teams when subagents suffice — teams have higher overhead and are experimental

Don't forget to set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — it's off by default

🧬

Custom Agents Native

Define reusable agent personas in markdown files with frontmatter. Each gets its own tools, model, permissions, skills, and optional persistent memory.

*"Specialists you design once and reuse forever"*

Locations: .claude/agents/reviewer.md ← project-scoped ~/.claude/agents/researcher.md ← global (all projects) Frontmatter: name, description, model, tools permissionMode, maxTurns, skills mcpServers, hooks, memory

Give agents narrow tools lists — an analyst doesn't need Edit or Write

Use memory: project for agents that should remember across sessions

Don't give agents broad permissions — use permissionMode: plan for read-only work

🔒

Permissions Native

Six permission modes with granular allow/deny/ask rules using glob-style patterns. Evaluation order: deny → ask → allow (first match wins).

*"Trust boundaries you actually control"*

Mode	Behavior
`default`	Prompt for first use of each tool
`acceptEdits`	Auto-accept file edits
`plan`	Read-only (analyze, don't modify)
`delegate`	Coordination-only for team leads
`dontAsk`	Auto-deny unless pre-approved
`bypassPermissions`	Skip all checks (containers only)

Rule syntax examples

Bash(npm run *) ← wildcard match Read(./.env) ← exact file Read(./secrets/**) ← directory glob WebFetch(domain:x.com) ← domain filter mcp__github__* ← MCP tool pattern Task(Explore) ← subagent control

Start with default mode, then add specific allow rules as you learn your patterns

Use deny rules for commands that should never run (e.g., Bash(rm -rf /))

Don't put broad wildcards in allow — Bash(*) defeats the entire purpose

📦

Sandbox Native

OS-level sandboxing for bash commands. Controls file system access, network access, and process isolation. Configurable via settings.

*"Defense in depth — not just permission prompts"*

Setting	Purpose
`sandbox.enabled`	Toggle sandboxing
`sandbox.network.allowedDomains`	Network allowlist
`sandbox.permissions.additionalDirectories`	Extra FS access

Enable sandbox in production/CI — it restricts file system and network at OS level

Whitelist only the domains your project actually needs in allowedDomains

Don't confuse sandbox with permissions — sandbox is OS-level, permissions are prompt-level

🏢

Managed Policies Native

Organization-level admin controls. Deployed to system paths, they override all user settings. Set allowed/denied MCP servers, enforce permission modes, and control model access.

*"Guardrails that individual users cannot override"*

System paths: /etc/claude-code/managed-settings.json ← Linux /etc/claude-code/CLAUDE.md ← org instructions /etc/claude-code/managed-mcp.json ← org MCP servers

What admins can control

Control	Effect
`allowedMcpServers`	Whitelist specific MCP servers
`deniedMcpServers`	Block specific MCP servers
`defaultMode`	Force a permission mode for all users
`deny` rules	Block specific tools/commands org-wide
`model`	Restrict available models

Use managed policies for compliance requirements that users must not bypass

Deploy org-wide CLAUDE.md for coding standards all teams must follow

Don't over-restrict — heavy managed policies frustrate developers and reduce adoption

The Complete Picture

DEFINE

CLAUDE.md → always-on instructions

SKILL.md → domain expertise

settings.json → configuration

.mcp.json → external tools

agents/*.md → custom agents

AUTOMATE

hooks → lifecycle triggers

PreToolUse → security gates

permissions → allow/deny/ask

sandbox → OS isolation

auto-memory → learn & persist

EXTEND

MCP servers → external APIs

plugins → packaged bundles

subagents → parallel workers

agent teams → coordination

keybindings → custom shortcuts

Variable	Purpose	Default
`ANTHROPIC_MODEL`	Model override	claude-sonnet-4-5-20250929
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Max output tokens	32768 (max 65536)
`BASH_DEFAULT_TIMEOUT_MS`	Bash command timeout	600000 (10 min)
`CLAUDE_CODE_DISABLE_AUTO_MEMORY`	Toggle auto-memory	0 (enabled)
`CLAUDE_CODE_EFFORT_LEVEL`	Reasoning effort (Opus 4.6)	high
`MAX_THINKING_TOKENS`	Extended thinking budget	—
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	Auto-compaction trigger %	—
`ENABLE_TOOL_SEARCH`	MCP lazy tool loading	auto
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`	Enable agent teams	0 (off)

Claude Code — Extension Architecture

Session Lifecycle — Where Everything Plugs In

The Complete Picture