Claude Code Architecture Deep DiveClaude Code Architecture Deep Dive

User: "Fix the bug in auth.ts"

Claude thinks: I need to read the file first
  -> Tool: Read(file_path="src/auth.ts")
  <- Returns: file content

Claude thinks: I see the issue, let me fix it
  -> Tool: Edit(file_path="src/auth.ts", old_string="...", new_string="...")
  <- Returns: success

Claude thinks: Let me verify by running tests
  -> Tool: Bash(command="npm test")
  <- Returns: All tests passed

Claude: "Fixed the null check bug in auth.ts. Tests passing."

# CLAUDE.md

## Project Overview
E-commerce API built with Node.js + PostgreSQL

## Development
- Run tests: npm test
- Start dev: npm run dev
- DB migration: npm run migrate

## Conventions
- Use camelCase for variables
- All API routes in /src/routes/
- Error handling via middleware

Claude Code
    |
    +-- Built-in Tools (Read, Write, Bash, etc.)
    |
    +-- MCP Client
         |
         +-- stdio:// -> Local MCP Server
         +-- sse:// -> Remote MCP Server
         +-- docker:// -> Containerized MCP

# .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'Running: $TOOL_INPUT' >> ~/.claude/bash.log"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "prettier --write $FILE_PATH"
      }
    ]
  }
}

Claude Code is a CLI AI Coding Assistant from Anthropic — not just a chatbot, but an autonomous agent that reads and writes files, runs commands, and does real work inside your codebase.

Today we go deep into the architecture behind it: how Claude Code is designed so that an AI can work both safely and efficiently.

---

Overview: What Is Claude Code?

Claude Code differs from ChatGPT or any web-based AI in one decisive way: it runs in your terminal, with genuine access to the filesystem, Git, and shell commands:

Key insight: Claude Code is not merely a wrapper around an API. It is an agentic system with the full set — tool use, memory, and an execution environment

---

Core Architecture Layers

Claude Code divides into four main layers:

1. User Interface Layer

Claude Code supports several interfaces:

• CLI Mode - runs in the terminal via the claude command
• VSCode Extension - embedded in the editor, with context awareness
• API/SDK Mode - for automation and CI/CD

2. Agent Controller — the Heart of the System

The Agent Controller is the "brain" that governs everything the system does:

Each iteration of the loop:

1. Receive input - the user message plus tool results from the previous iteration
2. Build context - assemble the system prompt, CLAUDE.md, and conversation history
3. Call Claude - send it to the API and get back a response plus tool calls
4. Execute tools - run the tools Claude selected (Read, Write, Bash, etc.)
5. Check completion - if the work is not finished, return to step 1

---

Tool System — What Claude Code Can Do

Claude Code ships with built-in tools that let the AI act on the codebase:

Tool Execution Flow

User: "Fix the bug in auth.ts"

Claude thinks: I need to read the file first
  -> Tool: Read(file_path="src/auth.ts")
  <- Returns: file content

Claude thinks: I see the issue, let me fix it
  -> Tool: Edit(file_path="src/auth.ts", old_string="...", new_string="...")
  <- Returns: success

Claude thinks: Let me verify by running tests
  -> Tool: Bash(command="npm test")
  <- Returns: All tests passed

Claude: "Fixed the null check bug in auth.ts. Tests passing."

Permission Model

Claude Code has a set of permission modes the user chooses from:

Mode	Auto-approve	Use case
Ask	None - asks every time	Learning, sensitive code
Auto-edit	Read/Edit automatically	Development workflow
Full auto	Every tool	CI/CD, automation

---

Context Management

One of the standing challenges for an AI agent is that the context window is finite. Claude Code manages it in several ways:

1. CLAUDE.md - Project Memory

A CLAUDE.md file in the project is persistent context, loaded every single time:

# CLAUDE.md

## Project Overview
E-commerce API built with Node.js + PostgreSQL

## Development
- Run tests: npm test
- Start dev: npm run dev
- DB migration: npm run migrate

## Conventions
- Use camelCase for variables
- All API routes in /src/routes/
- Error handling via middleware

2. Automatic Context Injection

Claude Code injects context automatically:

• Git status - current branch, uncommitted changes
• IDE selection - the code highlighted in VSCode
• Recent conversation - a compressed summary once it runs long
• Tool results - output from the preceding tools

3. Context Compaction

When a conversation grows too long, Claude Code compacts the older messages into a summary to save tokens:

---

MCP: Model Context Protocol

MCP is the protocol that lets Claude Code connect to external tools without limit:

MCP Architecture

Claude Code
    |
    +-- Built-in Tools (Read, Write, Bash, etc.)
    |
    +-- MCP Client
         |
         +-- stdio:// -> Local MCP Server
         +-- sse:// -> Remote MCP Server
         +-- docker:// -> Containerized MCP

MCP servers let Claude Code extend its capabilities without limit, and without anyone editing the core code.

---

Sub-agents: Parallel Execution

Claude Code can spawn sub-agents to work in parallel:

The sub-agent types available:

• Explore - search and understand the codebase
• Plan - plan the implementation
• General-purpose - ordinary work of any kind
• Background - runs async, never blocking the main agent

---

Security Model

Claude Code is designed to be safe by default:

1. Sandbox Execution

Bash commands run in a sandbox that:

• Limits network access
• Prevents access to files outside the working directory
• Blocks dangerous commands (rm -rf /, etc.)

2. Prompt Injection Defense

Claude Code stays wary of prompt injection from external sources:

• Tool outputs are sanitised
• File contents are marked untrusted
• The user gets a warning when suspicious content turns up

3. Git Safety

There are safeguards around Git operations:

• No force push to main/master without asking
• No reset --hard without a warning
• Commit messages must carry Co-Authored-By

---

Model Routing

Claude Code picks its model to suit the task:

Model	Use case	Trade-off
Opus	Complex reasoning, architecture	Slow, expensive
Sonnet	General coding, default	Balanced
Haiku	Simple tasks, sub-agents	Fast, cheap

The user can override that with the /model command, or set it in settings.

---

Hooks System

Claude Code carries hooks for injecting custom logic:

# .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'Running: $TOOL_INPUT' >> ~/.claude/bash.log"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "prettier --write $FILE_PATH"
      }
    ]
  }
}

The hook types supported:

• PreToolUse - before a tool runs
• PostToolUse - after a tool runs
• Notification - event notifications

---

Summary: Lessons Learned

From studying the Claude Code architecture, here is what we take away:

Key takeaway: building an AI agent that does real work means thinking about tool design, context management, and safety — not just prompt engineering