System Architecture

Relevant source files

• .claude-plugin/marketplace.json
• CHANGELOG.md
• LICENSE.md
• README.md
• demo.gif
• plugins/frontend-design/README.md
• plugins/frontend-design/skills/frontend-design/SKILL.md

This document provides a technical overview of Claude Code's high-level architecture, covering the core agent system, tool suite, plugin ecosystem, and how major components interact. For detailed documentation on specific subsystems, see the following pages:

• For CLI commands and user interaction, see CLI Commands & Interaction Modes
• For configuration files and settings hierarchy, see Configuration Management
• For plugin development and marketplace, see Plugin System
• For GitHub automation workflows, see GitHub Automation

Overview

Claude Code is built around an agent-based architecture with a modular tool system, extensive plugin support, and hierarchical configuration management. The system serves two primary use cases:

1. Interactive Developer Tool: A CLI application (claude command) that provides an AI coding assistant with session management, context handling, and tool execution
2. GitHub Automation Platform: Workflows that use Claude Code as an AI agent for issue triage, duplicate detection, and lifecycle management

Both use cases share the same core agent system, tools, and extension mechanisms.

Core Architecture

The following diagram shows the primary components and their relationships:

Sources: High-level diagrams provided (Diagram 1: Overall System Architecture), CHANGELOG.md1-100

Entry Point and CLI Layer

The primary entry point is the claude command, which supports both interactive mode (starting an agent session) and non-interactive subcommands:

Command	Purpose
claude	Start interactive session in current directory
claude --resume	Resume previous session from picker
claude --agent <name>	Start session with specific agent
claude --worktree	Start in isolated git worktree
claude auth login/logout/status	Manage authentication
claude doctor	Diagnostic tool for installation
claude mcp add/remove/list	Manage MCP server connections
claude plugin enable/disable/browse	Manage plugins
claude install	Installation wizard

The CLI layer handles:

• Argument parsing and validation
• Authentication state management
• Routing to appropriate subsystems (interactive session vs. subcommand)
• Environment variable processing (CLAUDE_CODE_* prefixes)

Sources: README.md1-73 CHANGELOG.md156-169

Session Management

Sessions are the unit of conversation persistence. Each session has:

Session storage structure:

• Location: ~/.claude/sessions/<session-id>/
• transcript.jsonl: Line-delimited JSON of messages
• .claude.json: Metadata (custom title, tags, branch, directory)
• Sessions can be resumed with /resume, forked with /fork, renamed with /rename

Key features:

• Resume: Restore conversation from any previous session
• Fork: Branch conversation at specific message
• PR Linking: Automatic association with GitHub PRs (via gh pr create or --from-pr)
• Custom Titles: User-defined names with /rename
• Compaction: Automatic summarization to fit context window

Sources: CHANGELOG.md55-100 High-level diagrams

Agent System Architecture

Main Agent

The main agent is the primary conversational interface. It:

• Processes user messages and generates responses
• Selects and executes tools based on task requirements
• Maintains conversation context and history
• Delegates work to subagents via the Task tool
• Responds to interrupt signals (Ctrl+C, ESC)

Subagents and Multi-Agent Patterns

Subagents are specialized instances spawned via the Task tool. They enable:

1. Parallel Execution: Multiple agents work simultaneously on independent tasks
2. Sequential Pipelines: Chain agents where each step feeds the next
3. Git Worktree Isolation: Agents work in temporary branches without affecting main workspace
4. Background Tasks: Long-running operations (Ctrl+B to background, Ctrl+F to kill)

Agent definitions (.claude/agents/*.md) specify:

• model: Which Claude model to use
• tools: Restricted tool access (e.g., Task(review-agent) allows only specific subagent types)
• memory: Persistent memory scope (user/project/local)
• background: Always run as background task

Example from marketplace: The code-review plugin uses parallel subagents with validation:

• Gate check (Haiku) → Summary (Sonnet) → 4 parallel reviewers (2 Sonnet + 2 Opus) → Validation → Output

Sources: CHANGELOG.md5-11 CHANGELOG.md206-210 .claude-plugin/marketplace.json29-38 High-level diagrams (Diagram 6)

Tool System

Tools are the agent's primary mechanism for interacting with the environment. Each tool has:

• Name: Identifier used by the model
• Input Schema: Structured parameters
• Execution Logic: Implementation that performs the action
• Permission Classification: Category for allow/ask/deny rules

Core Tools

Tool	Purpose	Permission Category
Bash	Execute shell commands	Bash (with sandbox option)
Read	Read file contents or PDF pages	Read
Write	Create/overwrite files	Write
Edit	Modify existing files with diffs	Write
Glob	Find files matching patterns	Read
Grep	Search file contents	Read
Task	Spawn subagent	Task
TaskUpdate	Update/delete background task	Task
TaskStop	Stop background task	Task
WebSearch	Search the web	WebTools
WebFetch	Fetch URL content	WebTools
MCPSearch	Discover MCP tools	MCPSearch

Tool Execution Flow

Permission Rules

Permission rules are pattern-based filters in settings.json:

Patterns use wildcard matching with tool name and parameter inspection. The classifier extracts relevant parameters (e.g., command for Bash, paths for file operations) and matches against rules.

Sources: CHANGELOG.md45-58 CHANGELOG.md199-200 High-level diagrams (Diagram 5)

Sandbox Environment

The Bash tool supports sandboxed execution for network isolation:

Configuration (settings.json):

Features:

• Network access limited to allowedDomains via iptables/ipset
• Specific commands can bypass sandbox via excludedCommands
• If enabled, autoAllowBashIfSandboxed skips permission prompts for sandboxed commands
• Applies only to Bash tool; other tools execute normally

Implementation: Uses init-firewall.sh script with iptables rules for network filtering. Requires NET_ADMIN capability in containerized environments.

Sources: CHANGELOG.md186-187 CHANGELOG.md199-200 CHANGELOG.md240-241 High-level diagrams (Diagram 4, Diagram 5)

Extension Mechanisms

Plugin System

Plugins extend Claude Code with custom commands, agents, skills, hooks, and MCP servers. Discovery paths (in order of precedence):

1. Built-in: .claude-plugin/ in repository
2. User: ~/.claude/plugins/
3. Project: .claude/plugins/
4. Additional: Directories specified via --add-dir

Plugin Structure (plugin.json):

Plugins are loaded at startup and can be managed via:

• claude plugin enable/disable <name>
• claude plugin browse (interactive marketplace browser)
• Hot-reload on file changes during development

Sources: CHANGELOG.md9-14 CHANGELOG.md120-121 .claude-plugin/marketplace.json1-151 High-level diagrams (Diagram 2)

Skill System

Skills are custom slash commands defined in SKILL.md files with YAML frontmatter:

Discovery paths:

• Project: .claude/skills/
• User: ~/.claude/skills/
• Plugin-provided: <plugin>/skills/
• Additional: --add-dir directories

Skills are invoked via slash commands (e.g., /example-skill arg1 arg2) and inject their content as system instructions. They can:

• Define custom commands with parameter substitution
• Request additional permissions or hooks (requires user approval)
• Access plugin name in skill descriptions for discoverability

Sources: CHANGELOG.md61-63 CHANGELOG.md208-209 CHANGELOG.md226-230 plugins/frontend-design/skills/frontend-design/SKILL.md1-42

Hook System

Hooks enable custom behavior at lifecycle events:

Hook Type	Trigger Point	Input Data
SessionStart	After session initialization	Session metadata
PreToolUse	Before tool execution	Tool name, parameters
PostToolUse	After tool execution	Tool name, result, duration
Stop	Session termination	Final message, transcript path
TeammateIdle	Subagent waiting for work	Agent ID, status
TaskCompleted	Subagent finished	Agent ID, result
Setup	Explicit maintenance trigger	Via --init, --init-only, --maintenance flags
ConfigChange	Settings file modified	Changed file path

Hook Definition (e.g., .claude/hooks/pre-tool-use.sh):

Hooks receive JSON input via stdin and can:

• Block execution (exit code 2 shows stderr to user)
• Add context to the model (additionalContext in PreToolUse)
• Run async operations (exit code 1 continues without waiting)
• Trigger external integrations (logging, notifications, policy enforcement)

Enterprise Control: allowManagedHooksOnly in managed settings prevents custom hooks, enforcing organizational policy.

Sources: CHANGELOG.md24-31 CHANGELOG.md54-55 CHANGELOG.md206-207 CHANGELOG.md424-425 CHANGELOG.md439-440

MCP (Model Context Protocol) Integration

MCP servers provide external tool integrations with three transport types:

Transport	Use Case	Configuration
stdio	Local processes	Command + args
HTTP	REST APIs	Base URL + endpoints
SSE	Server-sent events	Streaming connections

MCP Server Management:

• claude mcp add <url> - Add server
• claude mcp remove <name> - Remove server
• claude mcp list - Show configured servers
• Storage: ~/.claude/mcp-servers/

OAuth Support: MCP servers can use OAuth 2.0 with:

• Dynamic Client Registration (auto-discovery)
• Pre-configured credentials (--client-id, --client-secret)

Tool Discovery: By default, MCP tool descriptions load upfront. When they exceed 10% of context window, MCPSearch tool enables lazy loading via auto mode (configurable with auto:N syntax for N% threshold).

Sources: CHANGELOG.md106-107 CHANGELOG.md252-255 CHANGELOG.md420-421 CHANGELOG.md434-435 CHANGELOG.md458-459

Context and Memory Management

Context Window Management

Context Management Features:

• Automatic Compaction: Triggers at ~98% of effective context window (reserves space for max output tokens)
• Manual Compaction: /compact command for user-initiated summarization
• Partial Summarization: "Summarize from here" in message selector
• Token Tracking: Real-time display in status bar with usage percentages
• Prompt Caching: Caches system prompts and tool schemas for faster responses and reduced costs

Compaction Process:

1. Extract conversation history
2. Send to Anthropic Messages API for summarization
3. Replace history with compact summary
4. Preserve critical state (plan mode, session metadata, custom titles)

Sources: CHANGELOG.md38-45 CHANGELOG.md225-234 CHANGELOG.md329-330 CHANGELOG.md400-410 CHANGELOG.md452-453

Memory System

The memory system provides persistent state across sessions:

Scope	Storage Location	Use Case
user	~/.claude/memory/	Cross-project preferences, learnings
project	.claude/memory/	Project-specific context, patterns
local	.claude/memory/<session-id>/	Session-specific temporary state

Agent Memory Configuration (.claude/agents/*.md frontmatter):

Agents with memory specified automatically record and recall relevant information as they work. Memory is scoped per agent type and persists across invocations.

Sources: CHANGELOG.md207-208 CHANGELOG.md224-225 High-level diagrams (Diagram 1)

Configuration Hierarchy

Settings cascade through four levels with increasing precedence:

Enterprise-Only Controls (cannot be overridden):

• strictKnownMarketplaces: Block plugin sources
• allowManagedHooksOnly: Prevent custom hooks
• allowManagedPermissionRulesOnly: Centralize permission rules
• disableAllHooks: Force disable all hooks (respects managed hierarchy)

Common Settings:

• permissionRules: Allow/ask/deny patterns for tools
• sandbox: Network isolation configuration
• disallowedTools: Block specific tools
• bypassPermissions: Disable permission system (can be forced off)
• model: Default model selection
• enabledPlugins: Active plugin list
• extraKnownMarketplaces: Additional plugin sources
• spinnerVerbs, spinnerTipsOverride: UI customization

Configuration Management:

• /config command: Interactive settings editor with search
• Automatic backups: ~/.claude/backups/ (5 most recent, timestamped)
• Hot-reload: Changes detected and applied during session
• ConfigChange hook: Fires when files change (for auditing)

Sources: CHANGELOG.md28-31 CHANGELOG.md112-114 CHANGELOG.md292-294 CHANGELOG.md464-469 High-level diagrams (Diagram 5)

External Integrations

Anthropic API

Primary model provider with support for:

• Direct API: claude.api (formerly console.anthropic.com)
• AWS Bedrock: Regional deployment
• Google Vertex AI: GCP integration
• Anthropic Foundry: Enterprise platform

Model Support:

• Claude 3.5 Sonnet (standard and 1M context variants)
• Claude 3.5 Haiku
• Claude Opus 4.6 (with extended thinking and effort levels)
• Fast mode (Opus 4.6, reduced latency)

API Features:

• Streaming responses with progress indicators
• Prompt caching for reduced latency and cost
• Structured outputs (beta)
• Adaptive thinking and effort levels

Sources: CHANGELOG.md16-17 CHANGELOG.md110-111 CHANGELOG.md141-142 CHANGELOG.md194-195 CHANGELOG.md222-223

GitHub Integration

Used in two contexts:

1. PR Linking (interactive sessions):

   • Automatic association when creating PRs via gh pr create
   • Manual association via --from-pr <number|url>
   • Status indicator in prompt footer (approved/changes requested/pending/draft)

2. Automation Workflows (see GitHub Automation):

   • Issue triage and labeling
   • Duplicate detection
   • Oncall issue flagging
   • Stale issue management
   • Cross-repository notifications

Sources: CHANGELOG.md279-286 CHANGELOG.md326-328 High-level diagrams (Diagram 3)

Analytics and Telemetry

Statsig Integration: Event tracking for:

• Duplicate detection events
• Auto-close operations
• Issue lifecycle transitions
• Rate limit events (SDKRateLimitInfo, SDKRateLimitEvent)
• Tool decisions (tool_decision OTel events)

OpenTelemetry: Distributed tracing with:

• Span attributes: speed (fast mode visibility)
• Event tracking: Tool execution, hook invocation, compaction
• SDK mode support for external consumers

Sentry: Error reporting and monitoring (opt-in)

Sources: CHANGELOG.md113-115 CHANGELOG.md154-155 CHANGELOG.md75-76 High-level diagrams (Diagram 3)

Development Environment

Claude Code development uses a DevContainer for reproducible, isolated environments:

Container Configuration (.devcontainer/devcontainer.json):

• Base image: node:20
• Tools: git-delta, zsh, fzf
• Non-root user: node with limited sudo access
• Network firewall: init-firewall.sh with iptables rules
• Persistent volumes: workspace, config, command history, global npm packages

Orchestration:

• PowerShell script: run_devcontainer_claude_code.ps1
• Backend support: Docker Desktop or Podman Machine
• Automatic initialization and firewall setup

For detailed DevContainer documentation, see Development Environment.

Sources: High-level diagrams (Diagram 4), CHANGELOG.md115-116