Deep Dive Into Claude Code: Architecture, Agent Runtime, and Core Mechanisms

Anthropic's Claude Code has rapidly evolved from a simple AI-assisted CLI tool into something far more ambitious. Beneath its unassuming terminal interface lies a sophisticated Agent Runtime framework spanning over 1,884 TypeScript source files. This is not an AI "autocomplete" tool — it is a full-fledged system-level collaborator capable of understanding entire codebases, orchestrating parallel subagents, and managing complex multi-step workflows. This article dissects Claude Code's internal architecture, examines its five core mechanisms, explores its source-level design decisions, and distills practical best practices for senior developers and architects looking to leverage it in production environments.

1. The Big Picture: Claude Code as an Agent Runtime

The single most important insight from examining Claude Code's source is that Anthropic is not building a developer convenience tool. They are building an Agent Runtime — a general-purpose execution environment for autonomous AI agents that happen to focus on software engineering tasks.

1.1 Why This Distinction Matters

Traditional AI coding assistants (GitHub Copilot, Cursor autocomplete, etc.) operate in a request-response paradigm: the user types, the model responds, the user types more. The context window is narrow, the interaction is stateless, and the AI has no persistent understanding of your project.

Claude Code operates in an agentic loop paradigm:

User intent → Plan → Execute → Verify → Iterate → Deliver

     ↑                                         |

     └───────────── Feedback loop ─────────────┘

This loop runs continuously, with the agent maintaining rich state about your project, its own prior actions, and the evolving context of the task. The difference is as fundamental as the difference between a calculator and a spreadsheet.

1.2 Source Code at a Glance

The decompiled/leaked source code (widely analyzed in repositories like liuup/claude-code-analysis with 2.7k+ GitHub stars) reveals the following high-level structure:

• 1,884 TypeScript source files organized into distinct subsystems
• QueryEngine (~46K lines): The core engine handling all LLM dialogue logic, tool orchestration, and agent lifecycle
• Tool System: File I/O, terminal execution, code editing, search operations
• Command System: User-facing CLI commands, keyboard shortcuts, mode switching
• Multi-Agent Layer: Subagent spawning, task delegation, result aggregation
• Remote Bridge: Network communication, API orchestration, MCP integration
• Memory & Context: Session memory, project-level memory, long-term knowledge persistence

2. Three-Layer Architecture Deep Dive

Claude Code's architecture follows a clean three-layer design. Understanding these layers is essential for anyone looking to extend, customize, or deeply troubleshoot the system.

2.1 Interaction Layer (The User-Facing Surface)

This is where humans touch the system. It includes:

• Terminal UI (TUI): The primary interface with syntax highlighting, streaming output, and interactive prompts
• CLAUDE.md parser: Reads project-level configuration files that define coding standards, architecture conventions, and behavioral rules
• Command processor: Handles slash commands (/plan, /compact, /clear), keyboard shortcuts, and mode switches
• Permission gateway: All human-in-the-loop approval flows for dangerous operations (file deletion, command execution, etc.)

The interaction layer is intentionally thin — it is a presentation and routing layer that delegates everything substantive to the engine below.

# Example: CLAUDE.md project configuration

# Architecture

This is a monorepo using Turborepo. Packages are in /packages/*.

Always run tests before committing.

# Conventions

- Use TypeScript strict mode

- Prefer composition over inheritance

- All API endpoints must have Zod schema validation

- Error handling: use Result<T, E> pattern, never throw

# Testing

- Unit tests use vitest

- E2E tests use Playwright

- Run `pnpm test:affected` for targeted testing

2.2 Core Engine (The Brain)

The QueryEngine is the heart of Claude Code. At approximately 46,000 lines of TypeScript, it manages:

LLM Communication:

• Streaming API calls to Claude models (Sonnet, Opus, Haiku)
• Context window management (200K+ token capacity)
• Prompt construction with system instructions, tool definitions, conversation history, and injected context
• Token budget allocation between conversation, file contents, and tool results

Agent Loop Orchestration: The engine implements a ReAct-style (Reason + Act) agent loop:

// Simplified conceptual model of the agent loop

async function runAgentLoop(userMessage: string): Promise<void> {

  const messages = [{ role: "user", content: userMessage }];

  while (true) {

    // 1. REASON: Send context to LLM, get next action

    const response = await llm.complete({

      system: buildSystemPrompt(),

      messages: messages,

      tools: getAvailableTools(),

      // Extended thinking budget for complex tasks

      thinkingBudget: getThinkingBudget(),

    });

    // 2. ACT: Execute tool calls if present

    if (response.toolCalls.length > 0) {

      for (const toolCall of response.toolCalls) {

        const result = await executeTool(toolCall);

        messages.push({ role: "tool_result", content: result });

      }

      continue; // Loop back for next reasoning step

    }

    // 3. No tool calls means agent is done

    if (response.stopReason === "end_turn") {

      break;

    }

  }

}

Context Management:

• Compaction: When context approaches limits, the engine automatically summarizes older conversation turns while preserving critical information
• File prioritization: Smart ranking of which files to include in context based on relevance scores
• Tool result caching: Avoids re-fetching unchanged file contents across turns

2.3 Tool System (The Hands)

The tool system is Claude Code's interface to the outside world. Each tool is a well-defined capability with strict input/output schemas:

Core Built-in Tools:

• FileReadTool: Read file contents with line range support, encoding detection, and large file chunking
• FileEditTool: Make targeted edits using search/replace blocks with fuzzy matching tolerance
• FileWriteTool: Create or overwrite files with directory auto-creation
• BashTool: Execute shell commands with timeout management, output streaming, and working directory tracking
• SearchTool: Grep, glob, and semantic search across the codebase
• WebFetchTool: Retrieve and parse web content for documentation or API references

Tool Execution Safety: Every tool invocation passes through a permission layer. The system categorizes tools by risk level:

• Read-only operations (file read, search): Auto-approved
• Write operations (file edit, file write): Require per-session approval or explicit whitelist
• Destructive operations (file delete, command execution): Require individual confirmation with human review

3. The Five Core Mechanisms

Claude Code's power comes not from individual features but from five integrated mechanisms that form a complete collaboration system.

3.1 Skills — Pre-packaged Workflow Templates

Skills are reusable, parameterized workflow definitions that encapsulate multi-step operations. Think of them as "macro operations" that eliminate repetitive instruction-giving.

A Skill defines:

• Trigger condition: When this Skill should activate
• Step sequence: Ordered list of actions (tool calls, LLM prompts, conditional logic)
• Validation criteria: How to verify the Skill executed correctly
• Rollback procedure: What to do if something goes wrong

// Conceptual Skill definition: "Create REST API Endpoint"

{

  "name": "create-rest-endpoint",

  "description": "Creates a new RESTful API endpoint with validation, service layer, and tests",

  "parameters": {

    "resource_name": { "type": "string", "required": true },

    "methods": { "type": "array", "default": ["GET", "POST", "PUT", "DELETE"] },

    "include_auth": { "type": "boolean", "default": true }

  },

  "steps": [

    "Analyze existing endpoint patterns in the project",

    "Generate route definition following project conventions",

    "Create Zod validation schemas for request/response",

    "Implement service layer with error handling",

    "Generate unit tests for all methods",

    "Update API documentation",

    "Run tests to verify integration"

  ],

  "validation": "All generated tests pass"

}

The key architectural insight is that Skills are not hardcoded — they are interpreted by the LLM. The system prompt instructs Claude to follow the Skill's step sequence, but the actual code generation, file navigation, and decision-making are done by the model. This makes Skills flexible and adaptive rather than rigid scripts.

3.2 Hooks — Event-Driven Automation Triggers

Hooks implement an event-driven architecture within Claude Code. They follow a simple but powerful pattern: when event X occurs, automatically execute action Y.

Common hook points include:

• pre-commit: Triggered before code is committed; auto-run linting, formatting, type checking
• post-file-save: Triggered after a file is written; trigger incremental compilation or related test execution
• post-generation: Triggered after code generation completes; auto-run relevant test suites
• pre-tool-execution: Triggered before any tool runs; enable additional validation or logging
• session-start: Triggered when a new session begins; load project context, restore prior state

# Example hooks configuration in .claude/hooks.yaml

hooks:

  - event: post-generation

    condition:

      tool: FileEditTool

      file_pattern: "src/**/*.ts"

    action:

      run: "pnpm vitest run --changed"

      on_failure: "notify_user"

  - event: pre-commit

    action:

      sequence:

        - "pnpm lint:fix"

        - "pnpm format"

        - "pnpm type-check"

      abort_on_failure: true

The brilliance of Hooks is that they transform things humans forget to do into things the system always does. They are the programmable "muscle memory" of the agent.

3.3 Plugins — Composable Feature Packs

If Skills are individual operations and Hooks are event reactions, Plugins are the bundling mechanism that packages them into distributable units.

A Plugin can contain:

• Multiple Skills
• Multiple Hooks
• Custom tool definitions
• Configuration overrides
• MCP server registrations
• Documentation and metadata

This makes Plugins the primary mechanism for team-level standardization. A team can create a Plugin that encodes their entire development workflow — from code generation conventions to testing standards to deployment procedures — and share it across the organization.

// Conceptual Plugin manifest

export default {

  name: "@acme/node-api-plugin",

  version: "2.1.0",

  skills: [

    "./skills/create-endpoint.skill",

    "./skills/create-middleware.skill",

    "./skills/generate-openapi.skill"

  ],

  hooks: [

    { event: "post-generation", action: "./hooks/run-tests.sh" },

    { event: "pre-commit", action: "./hooks/lint-and-format.sh" }

  ],

  config: {

    testFramework: "vitest",

    validationLibrary: "zod",

    orm: "prisma",

    authPattern: "jwt-bearer"

  },

  mcpServers: {

    "acme-deploy": {

      command: "npx",

      args: ["@acme/deploy-mcp-server"]

    }

  }

};

3.4 MCP Servers — External Service Integration Bridge

Model Context Protocol (MCP) is the mechanism that allows Claude Code to "step outside the editor" and interact with external systems. MCP Servers act as standardized adapters that expose external capabilities to the agent.

Through MCP Servers, Claude Code can:

• Query databases directly and inspect schema
• Call third-party APIs (Slack, Jira, AWS, GCP)
• Interact with cloud services for deployment and monitoring
• Access internal company tools and dashboards
• Operate Kubernetes clusters and CI/CD pipelines

// MCP server configuration in .claude/settings.json

{

  "mcpServers": {

    "postgres": {

      "command": "npx",

      "args": ["-y", "@modelcontextprotocol/server-postgres",

               "postgresql://localhost:5432/mydb"]

    },

    "github": {

      "command": "npx",

      "args": ["-y", "@modelcontextprotocol/server-github"],

      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }

    },

    "kubernetes": {

      "command": "npx",

      "args": ["-y", "@strowk/mcp-k8s-go"]

    }

  }

}

MCP transforms Claude Code from a code editor into a full-stack operations agent. The same agent that writes your code can deploy it, monitor it, and debug it in production.

3.5 Subagents — Parallel Processing via Task Decomposition

The Subagent mechanism is where Claude Code achieves true parallelism. When faced with a complex task, the primary agent can decompose it into independent sub-tasks and delegate each to a dedicated subagent.

Architecture of Subagent delegation:

Primary Agent

├── Analyzes task, identifies independent work streams

├── Spawns Subagent A: Refactor API layer

│   ├── Reads relevant files

│   ├── Makes edits

│   └── Runs targeted tests

├── Spawns Subagent B: Update data access layer

│   ├── Reads relevant files

│   ├── Makes edits

│   └── Runs targeted tests

├── Spawns Subagent C: Update integration tests

│   ├── Reads relevant files

│   ├── Makes edits

│   └── Runs targeted tests

├── Collects results from all subagents

├── Resolves conflicts (if any)

└── Validates integrated result

Each subagent runs with its own context window and tool permissions, enabling true non-blocking parallel execution. The primary agent acts as coordinator, handling dependencies, resolving conflicts, and ensuring coherence across subagent outputs.

This is particularly powerful for large-scale refactoring where changes span multiple layers of the architecture.

4. The Memory System: Six Dimensions of Context

One of the most sophisticated aspects of Claude Code's architecture is its multi-layered memory system. Understanding this is key to making the agent work effectively over long sessions and across projects.

4.1 Instruction Memory

Instruction memory is loaded at session start from configuration files. It includes:

• CLAUDE.md at the project root (project-level rules)
• ~/.claude/CLAUDE.md (user-level global preferences)
• Plugin-provided instructions
• System prompt defaults

This memory is always present in every LLM call throughout the session. It is the most expensive (in tokens) but most reliable form of memory.

4.2 Session Memory (Conversation Context)

This is the rolling buffer of the current conversation — user messages, assistant responses, and tool results. The engine manages this carefully:

• Older turns are compacted (summarized) when approaching context limits
• Recent turns are preserved in full fidelity
• Tool results (especially file contents) may be truncated or replaced with summaries after they are no longer actively needed

4.3 Project Memory (Cross-Session Persistence)

Between sessions, Claude Code can persist key learnings about your project:

• Architecture decisions and their rationale
• Known patterns and anti-patterns in the codebase
• Recurring issues and their resolutions
• Team conventions discovered during the session

This is stored in project-local files (typically .claude/memory/) and loaded automatically in future sessions.

4.4 Filesystem as Implicit Memory

Every file the agent reads becomes part of its working memory. The 200K+ token context window means Claude Code can hold a substantial portion of a small-to-medium project in context simultaneously, understanding cross-file dependencies, import relationships, and call graphs.

4.5 Auto-Compaction and Summarization

When context grows too large, the engine triggers automatic compaction:

• Older conversation turns are summarized
• Tool results from earlier steps are condensed
• The system maintains a "summary chain" that preserves key decisions while reducing token count

4.6 External Knowledge via MCP

Through MCP servers, the agent can query external knowledge bases, documentation sites, and databases, effectively extending its memory beyond what fits in the context window.

5. Four Advanced Operating Modes

Beyond the default interactive mode, Claude Code offers four specialized modes that dramatically change its behavior profile.

5.1 Plan Mode — Think Before You Act

The recommendation from Anthropic's team is striking: spend 90% of your time in Plan mode. In Plan mode, the agent follows a strict sequence:

1. User describes the requirement

2. Agent outputs a detailed execution plan

3. User reviews, adjusts, and approves the plan

4. Agent executes the approved plan step by step

5. Agent reports progress and deviations

This prevents the common failure mode of agents "rushing to code" and discovering halfway through that their approach was wrong. Plan mode is a token-saving, quality-improving discipline.

When to use Plan mode:

• Any task that touches more than 3 files
• Architecture decisions
• Refactoring operations
• New feature implementation
• Debugging complex issues

When you can skip it:

• Simple, single-file edits
• Quick documentation updates
• Trivial bug fixes with known solutions

5.2 Extended Thinking (Deep Reasoning Mode)

For tasks requiring deep analytical reasoning — architecture design, complex algorithm implementation, performance optimization — Extended Thinking mode (sometimes called "ultrathink") instructs the model to spend significantly more computation on internal reasoning before producing output.

# Activating extended thinking

claude --thinking-budget high

# Or within a session

> /think deep

# Or using the community shorthand

> ultrathink

Practical guidance:

• Use for: system design, complex debugging, algorithmic challenges, security-sensitive code
• Avoid for: boilerplate generation, simple CRUD operations, formatting tasks
• Cost impact: Extended thinking can increase token usage by 3-5x, so use judiciously

5.3 Sandbox Mode — Controlled Execution Environment

Sandbox mode creates a bounded execution environment that restricts the agent's capabilities:

• File system restrictions: Only allow read/write to specified directories
• Command restrictions: Block dangerous shell commands (rm -rf, sudo, etc.)
• Network restrictions: Limit or disable external network access
• Time restrictions: Set maximum execution time per operation

// Sandbox configuration

{

  "sandbox": {

    "allowed_paths": ["./src", "./tests", "./docs"],

    "blocked_commands": ["rm -rf", "sudo", "chmod 777", "curl.*|.*sh"],

    "max_execution_time_seconds": 300,

    "network": "restricted",

    "max_file_size_kb": 1024

  }

}

Use Sandbox mode when operating near production code, when onboarding new team members who will use the agent, or when running headless automation.

5.4 Headless Mode — CI/CD Pipeline Integration

Headless mode runs Claude Code without any interactive terminal interface, making it suitable for embedding in automated pipelines:

# GitHub Actions integration example

name: AI Code Review

on: [pull_request]

jobs:

  ai-review:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

        with:

          fetch-depth: 0

      - name: Run Claude Code Review

        env:

          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

        run: |

          claude --headless \

            - -prompt "Review this PR. Check for bugs, performance issues,

                      security vulnerabilities, and convention violations.

                      Output a structured review report." \

            - -output-format json \

            - -max-turns 20 \

            > review_report.json

      - name: Post Review Comments

        run: |

          # Parse review_report.json and post PR comments

          node scripts/post-review.js review_report.json

Headless mode use cases include:

• Automated PR code review with structured feedback
• Build failure analysis and auto-fix attempts
• Scheduled technical debt scanning
• Automated documentation generation
• Test failure triage and root cause analysis

6. Model Integration and Flexibility

While designed for Claude models, the architecture supports alternative LLM backends, which is crucial for teams with data sovereignty requirements or cost optimization needs.

6.1 Compatible Alternative Models

• DeepSeek: Strong code generation capabilities, cost-effective for algorithm-intensive tasks
• GLM-4: Excellent Chinese language understanding, suitable for Chinese-language projects
• Kimi K2: Long context window support, effective for large project analysis
• Qwen (通义千问): Alibaba ecosystem integration, good for Alibaba Cloud stack projects

6.2 Configuration Pattern

{

  "model_provider": {

    "type": "openai-compatible",

    "endpoint": "https://api.deepseek.com/v1",

    "model": "deepseek-coder-v2",

    "api_key_env": "DEEPSEEK_API_KEY",

    "context_window": 128000,

    "capabilities": {

      "tool_use": true,

      "streaming": true,

      "extended_thinking": false

    }

  }

}

7. Practical Best Practices and Anti-Patterns

After extensive real-world usage, several patterns emerge that consistently produce better outcomes.

7.1 The Verification Loop Pattern

The single most impactful practice: always make the AI verify its own work before presenting it to you.

Standard flow (fragile):

  Requirement → Generate code → Human review → Commit

Verification loop (robust):

  Requirement → Generate code → Self-review → Self-fix → Run tests → Human review → Commit

Teams using the verification loop pattern report:

• 2-3x improvement in first-pass code quality (measured by bug count)
• Rework rate dropping from 20%+ to under 5%
• Significant reduction in human review time

The mechanism works because code generation and code review are fundamentally different cognitive tasks. Even the same model, when switching to a "reviewer" mindset, catches issues it missed as a "generator."

7.2 Parallel Instance Strategy

Running multiple Claude Code instances simultaneously can yield dramatic throughput improvements:

# Terminal 1: Backend API work

claude --session backend-api

# Terminal 2: Frontend component work

claude --session frontend-ui

# Terminal 3: Test suite generation

claude --session test-generation

# Terminal 4: Documentation updates

claude --session docs-update

Teams report up to 19x throughput improvement with well-coordinated parallel instances, though the practical multiplier depends heavily on task independence and coordination overhead.

7.3 The Evolving CLAUDE.md Pattern

Treat CLAUDE.md as a living document that improves over time:

1. After every code review: Add common issues found as rules
2. After every PR feedback: Extract conventions from reviewer comments
3. Monthly cleanup: Remove outdated rules, consolidate duplicates, sharpen vague guidance
4. Measure effectiveness: Track whether rules actually prevent issues

# CLAUDE.md — Evolving Rules Section

## Learned Rules (Updated 2026-03-15)

<!-- These rules were added after recurring review feedback -->

- NEVER use `any` type — always provide explicit types

- ALWAYS handle loading, error, and empty states in React components

- Database queries MUST use parameterized statements (security rule from PR #342)

- API responses MUST include correlation IDs for tracing (from incident post-mortem)

7.4 Common Anti-Patterns to Avoid

Anti-pattern 1: Vague Task Descriptions

BAD:  "Fix the login bug"

GOOD: "Users report that clicking 'Login' with valid credentials

       on Chrome 120 shows 'Session expired' error. Investigate

       the auth flow in src/auth/, check token refresh logic,

       and fix the root cause."

Anti-pattern 2: Skipping Plan Mode for Complex Tasks Always use Plan mode when changes span multiple files or architectural layers. The upfront planning cost is recovered many times over in reduced rework.

Anti-pattern 3: Ignoring Context Window Budget Be mindful that loading large files into context consumes tokens. Use targeted file reads rather than loading entire directories.

Anti-pattern 4: Not Using Hooks for Repetitive Checks If you find yourself manually asking Claude to "run tests" or "check linting" after every change, automate it with a Hook.

8. Architecture Comparison: Claude Code vs. Traditional Agent Frameworks

Understanding how Claude Code's architecture compares to other agent frameworks helps clarify its design choices:

vs. LangChain/LangGraph:

• Claude Code is a complete runtime with built-in tools, UI, and memory; LangChain is a library for building agents
• Claude Code is opinionated and optimized for software engineering; LangChain is general-purpose
• LangGraph offers more granular control over agent state machines; Claude Code abstracts this away

vs. AutoGPT/OpenHands:

• Claude Code has a more mature tool system specifically designed for code manipulation
• AutoGPT-style agents tend toward autonomous operation; Claude Code maintains human-in-the-loop by default
• Claude Code's context management and compaction are more sophisticated

vs. Aider:

• Aider is lighter-weight and focuses specifically on code editing
• Claude Code provides a richer ecosystem (Skills, Hooks, Plugins, MCP)
• Aider is more transparent about its edits; Claude Code is more autonomous

9. Key Takeaways

1. Claude Code is an Agent Runtime, not a coding assistant. Its architecture — from the QueryEngine to the Subagent system — is designed for autonomous, multi-step task execution. Treat it accordingly.

2. The five mechanisms are interlocking. Skills provide reusable workflows, Hooks provide event-driven automation, Plugins enable team distribution, MCP extends capabilities outward, and Subagents enable parallelism. Use them together for maximum effect.

3. Plan mode is not optional for serious work. The 90% rule exists because premature execution is the primary source of wasted tokens and poor outcomes.

4. The verification loop is the single highest-ROI practice. Making the agent review its own output before presenting it catches a significant portion of errors at zero human cost.

5. CLAUDE.md is your most valuable configuration asset. Treat it as a living document that encodes your team's collective knowledge and evolving standards.

6. Sandbox and Headless modes unlock production use cases. From automated code review to CI/CD integration, these modes transform Claude Code from a developer tool into an infrastructure component.

7. The memory system requires active management. Understanding how instruction memory, session memory, and project memory interact helps you configure the system for optimal performance over long sessions.

10. Further Reading and Resources

• Source code analysis repository: github.com/liuup/claude-code-analysis — community-maintained deep dive into Claude Code's TypeScript source
• Official Anthropic documentation: Comprehensive API references and configuration guides
• MCP specification: modelcontextprotocol.io — understanding the Model Context Protocol for building custom integrations
• Agent SDK documentation: For embedding Claude Code capabilities into custom automation systems
• Community patterns: The Claude Code community maintains growing libraries of Skills, Hooks, and Plugins that serve as excellent reference implementations

Claude Code represents a paradigm shift from AI-assisted coding to AI-autonomous engineering. The teams that will benefit most are those that understand its architecture deeply, configure it thoughtfully, and evolve their practices alongside it. The agent runtime era of software development has arrived — the question is no longer whether to adopt these tools, but how to adopt them well.