Core Systems

Relevant source files

• CHANGELOG.md
• LICENSE.md
• README.md
• demo.gif

This page provides technical documentation of Claude Code's internal architecture and the subsystems that power its functionality. It covers the fundamental building blocks that enable agentic coding, multi-agent orchestration, permission management, and plugin extensibility.

For user-facing documentation on configuration and usage, see Configuration Management and CLI Commands & Interaction Modes. For details on specific subsystems, refer to the child pages listed in each section below.

Architecture Overview

Claude Code's architecture is organized around several core subsystems that work together to provide an agentic coding experience. The system follows a layered approach where the CLI interface routes user input through session management to the agent system, which orchestrates tool execution under permission controls while managing context windows and triggering lifecycle hooks.

Sources: CHANGELOG.md1-100 diagrams from context

Core System Responsibilities

System	Primary Responsibility	Key Configuration
Agent System	Execute user requests, spawn subagents, manage task lifecycle	.claude/agents/*.md
Tool System	Provide capabilities (bash, file ops, web, MCP)	settings.json disallowedTools
Permission System	Control tool execution with allow/ask/deny rules	settings.json permission rules
Context Manager	Track token usage, trigger auto-compaction	Context window limits
Hook System	Inject custom behavior at lifecycle events	.claude/hooks/*.sh, plugin hooks
Plugin System	Discover and load extensions	marketplace.json, plugin.json
Skill System	Load custom slash commands	.claude/skills/*.md
MCP Integration	Connect to external tool servers	settings.json MCP servers

Sources: CHANGELOG.md1-50 README.md1-73

Request Processing Flow

This diagram shows how a user message flows through Claude Code's core systems, from input to execution. It maps natural language concepts to the actual execution path.

Sources: CHANGELOG.md241-320 CHANGELOG.md450-520

System Component Details

Agent System

The agent system orchestrates all AI-powered operations, including spawning subagents for parallel work and managing background tasks. Agents can execute in isolated git worktrees and support multi-agent teams.

Key Features:

• Main agent handles user interaction
• Subagents spawned via Task tool for parallel execution
• Background execution with Ctrl+B (since 2.1.49)
• Worktree isolation with --worktree flag
• Agent teams with tmux-based coordination
• Agent definitions in .claude/agents/*.md with frontmatter

Configuration Fields:

• model: Override default model for agent
• tools: Restrict available tools
• background: true: Auto-background execution
• isolation: "worktree": Use temporary git worktree
• memory: Scope for persistent memory (user/project/local)
• hooks: Agent-scoped lifecycle hooks

For detailed documentation, see Agent System & Subagents.

Sources: CHANGELOG.md5-8 CHANGELOG.md222-224 CHANGELOG.md563-567

Tool System

Tools provide Claude with capabilities to interact with the development environment. The system includes built-in tools and supports external tools via MCP servers.

Built-in Tools:

Tool Name	Purpose	Permission Required
Bash	Execute shell commands	Bash(command pattern)
Read	Read file contents	Read(path pattern)
Write	Create new files	Write(path pattern)
Edit	Modify existing files	Edit(path pattern)
Task	Spawn subagent	Task or Task(AgentName)
TaskUpdate	Manage background tasks	TaskUpdate
TaskStop	Stop background task	TaskStop
Search	Find in files (ripgrep)	Search
Glob	List files matching pattern	Glob
WebSearch	Search the web	WebSearch
WebFetch	Fetch URL content	WebFetch
LSP	Language server queries	LSP
MCPSearch	Discover MCP tools	MCPSearch

Tool Configuration:

• disallowedTools in settings.json: Disable specific tools
• --tools CLI flag: Restrict tools in interactive mode
• sandbox.enabled: Isolate Bash execution

For detailed documentation, see Tool System & Permissions.

Sources: CHANGELOG.md244-247 CHANGELOG.md318-319 CHANGELOG.md565-566

Permission System

The permission system controls tool execution through a classifier that matches tool invocations against allow/ask/deny rules with wildcard pattern support.

Permission Decisions:

• allow: Execute without prompting
• ask: Prompt user for approval
• deny: Block execution

Rule Syntax:

• Bash(*): Match all bash commands
• Bash(git *): Match commands starting with "git"
• Bash(* install): Match commands ending with "install"
• Read(/etc/*): Match files in /etc/
• Task(AgentName): Control specific agent spawning

Settings Hierarchy:

1. Enterprise settings (managed-settings.json) - highest priority
2. User settings (~/.claude/settings.json)
3. Project settings (.claude/settings.json)
4. Local settings (settings.local.json)
5. Session-only rules (runtime)

Enterprise Controls:

• allowManagedPermissionRulesOnly: Force centralized rules
• allowManagedHooksOnly: Prevent custom hooks
• strictKnownMarketplaces: Block non-approved plugins

For detailed documentation, see Tool System & Permissions.

Sources: CHANGELOG.md562 CHANGELOG.md449 CHANGELOG.md26-30

Context Window Management

The context manager tracks token usage across the conversation and triggers automatic compaction when nearing limits. It handles both input and output tokens with reserve space for model responses.

Token Tracking:

• Real-time usage display in status bar
• Percentage-based warning thresholds
• Separate tracking for cache hits
• MCP tool description impact on context

Compaction Strategies:

• Auto-compact at ~98% of effective context window
• Manual compaction via /compact command
• Preserves recent messages and user intent
• Strips images and PDF blocks before compaction
• Maintains plan mode state through compaction

Context Optimization:

• Prompt cache for tool descriptions and system prompts
• Deferred MCP tool loading with MCPSearch auto mode
• Skill description budget scales with context window (2%)
• Background task history trimming

For detailed documentation, see Context Window & Compaction.

Sources: CHANGELOG.md38 CHANGELOG.md314-315 CHANGELOG.md452-453 CHANGELOG.md458

Hook System

Hooks provide lifecycle event interception points for custom behavior injection without modifying core logic. Hooks can be defined at multiple scopes and support both synchronous and asynchronous execution.

Hook Types:

Hook Event	Trigger	Use Cases
Setup	--init, --init-only, --maintenance flags	Repository setup, dependency installation
SessionStart	Session begins	Load project context, configure environment
ConfigChange	Settings files modified during session	Enterprise security auditing
PreToolUse	Before tool execution	Security warnings, input validation
PostToolUse	After tool execution	Logging, result processing
TeammateIdle	Subagent waiting for work	Coordination logic
TaskCompleted	Subagent finishes	Aggregate results
Stop	Session ends	Cleanup, save state

Hook Definition:

• Shell scripts in .claude/hooks/*.sh
• Agent/skill/command frontmatter hooks field
• Plugin-provided hooks via plugin.json
• once: true for single execution

Hook Scope:

• Global hooks apply to all sessions
• Agent-scoped hooks apply during agent execution
• Skill-scoped hooks apply when skill executes

Hook Execution:

• Timeout: 10 minutes (changed from 60 seconds in 2.1.3)
• Exit code 2: Block operation
• additionalContext return: Inject context to model
• Windows: Uses Git Bash for execution

For detailed documentation, see Hook System.

Sources: CHANGELOG.md424 CHANGELOG.md205-206 CHANGELOG.md24 CHANGELOG.md567 CHANGELOG.md90

MCP Server Integration

MCP (Model Context Protocol) servers provide external tool integrations via HTTP, SSE, or stdio transports. Claude Code discovers tools dynamically and supports OAuth for authenticated servers.

Transport Types:

• HTTP: Polling-based communication
• SSE: Server-sent events for push updates
• stdio: Standard input/output pipes

Server Features:

• Dynamic tool discovery
• OAuth 2.0 with Dynamic Client Registration
• Pre-configured client credentials for non-DCR servers
• list_changed notifications for dynamic tool updates
• Tool search with auto-enable threshold

Configuration:

MCPSearch Tool:

• Defers tool loading when descriptions exceed 10% of context
• Auto mode enabled by default
• Configurable threshold: auto:N (0-100%)

For detailed documentation, see MCP Server Integration.

Sources: CHANGELOG.md106 CHANGELOG.md252 CHANGELOG.md458 CHANGELOG.md564

Plugin System

The plugin system enables extensibility through marketplace-distributed packages containing commands, agents, skills, hooks, and MCP server definitions.

Plugin Structure:

• plugin.json: Metadata and component definitions
• agents/*.md: Custom agent definitions
• skills/*.md: Slash commands
• hooks/*.sh: Lifecycle hooks
• settings.json: Default plugin configuration
• MCP server definitions

Discovery Paths:

1. Official marketplace: marketplace.json
2. Custom marketplaces: extraKnownMarketplaces
3. --add-dir directories: enabledPlugins

Plugin Management:

• Installation: claude plugin install <name>
• Enable/disable: claude plugin enable/disable <name>
• Scopes: user, project, managed
• Hot-reload: Changes detected without restart (since 2.1.0)
• Git submodule support

Enterprise Controls:

• strictKnownMarketplaces: Block non-approved sources
• Managed plugins enforce organizational policies

For detailed documentation, see Plugin System.

Sources: CHANGELOG.md9 CHANGELOG.md111-112 CHANGELOG.md120 CHANGELOG.md455

Skill System

Skills provide custom slash commands defined in markdown files with YAML frontmatter. They support hot-reload, agent forking, and permission declarations.

Skill Definition (SKILL.md):

Discovery Locations:

• User skills: ~/.claude/skills/*.md
• Project skills: .claude/skills/*.md
• Plugin skills: Referenced in plugin.json
• --add-dir skills: Nested .claude/skills/

Hot-Reload:

• Skills created/modified are immediately available
• No session restart required (since 2.1.0)

Variable Substitution:

• ${CLAUDE_SESSION_ID}: Current session ID
• $0, $1, etc.: Individual arguments
• $ARGUMENTS[0], $ARGUMENTS[1]: Indexed access

For detailed documentation, see Skill System.

Sources: CHANGELOG.md542-543 CHANGELOG.md467 CHANGELOG.md438-439 CHANGELOG.md61-62

Sandbox Environment

The sandbox provides isolated execution for bash commands with network access controls and command restrictions.

Sandbox Configuration:

Security Features:

• Network isolation with domain allowlisting
• Unix socket blocking
• Local port binding control
• Proxy support for corporate environments
• Command-level exemptions

Implementation:

• Applies only to Bash tool (not Read/Write/Edit)
• Uses process-level network controls
• Cannot write to .claude/skills directory

For detailed documentation, see Sandbox Environment.

Sources: CHANGELOG.md186 CHANGELOG.md199 CHANGELOG.md240

System Interaction Patterns

Agent Orchestration

Sources: CHANGELOG.md5-8 CHANGELOG.md116

Permission Flow

Sources: CHANGELOG.md562 CHANGELOG.md26-30

Hook Execution

Sources: CHANGELOG.md24 CHANGELOG.md555 CHANGELOG.md90

Configuration File Hierarchy

Claude Code uses a multi-level configuration system where settings cascade from enterprise to session scope.

Configuration Locations:

Scope	Location	Use Case
Enterprise	C:\Program Files\ClaudeCode\managed-settings.json (Windows) /etc/claude/managed-settings.json (Unix)	Organizational policies
User	~/.claude/settings.json	Personal preferences
Project	.claude/settings.json	Repository configuration
Local	.claude/settings.local.json	Machine-specific overrides
Session	Runtime memory	Temporary permission grants

Sources: CHANGELOG.md536 CHANGELOG.md26-30

Memory System Architecture

Claude Code maintains persistent memory across conversations with configurable scopes for different retention needs.

Memory Scopes:

Scope	Storage Location	Lifetime	Use Case
user	~/.claude/memory/user/	Permanent	User preferences, global facts
project	.claude/memory/project/	Per repository	Project-specific context
local	.claude/memory/local/	Machine-specific	Local environment details

Memory Configuration:

• Agent frontmatter: memory: user / memory: project / memory: local
• Automatic recording during agent execution
• Recall during subsequent sessions

Sources: CHANGELOG.md207 CHANGELOG.md224

Session Management

Sessions represent conversation continuity with support for resume, fork, and remote synchronization.

Session Operations:

• --resume [id]: Continue previous session
• /fork: Branch conversation
• /clear: Reset conversation (preserves session)
• /rename [title]: Set custom session name
• --from-pr <number>: Resume PR-linked session

Session Storage:

• Transcript files: Conversation history
• Session metadata: Title, tags, branch
• Context state: Compacted summaries
• Background task state: Running/completed tasks

Remote Sessions:

• OAuth users: Browse claude.ai sessions
• /teleport: Resume remote session locally
• Automatic PR linking via gh pr create

Sources: CHANGELOG.md279-280 CHANGELOG.md216-218 CHANGELOG.md359-361

Performance Optimizations

Claude Code implements several performance optimizations to reduce latency and memory usage:

Startup Optimizations:

• Deferred SessionStart hook execution (~500ms reduction)
• Cached MCP auth failures
• Batched MCP tool token counting
• Deferred Zod schema construction
• Pre-warming file suggestion index
• Skipped API calls in non-interactive mode

Runtime Optimizations:

• Session-based file suggestion caching
• Progressive session enrichment (68% memory reduction)
• Stream buffer release after completion
• Agent context cleanup after task completion
• Tree-sitter parser reset to prevent WASM growth
• Yoga layout reference cleanup
• Terminal rendering data layout optimization

Context Optimizations:

• Prompt cache for system prompts and tool descriptions
• Deferred MCP tool loading with MCPSearch
• Skill description budget scaling
• Image and PDF stripping before compaction

Sources: CHANGELOG.md40 CHANGELOG.md25-27 CHANGELOG.md121-122 CHANGELOG.md265 CHANGELOG.md524