Decoding Claude Code

What actually happens when you ask an AI to fix your code? Where does the thinking happen? Does your code leave your machine? And why is it eating your RAM?

A technically precise, cricket-flavoured guide to the architecture of Claude Code.

Your Machine vs. Anthropic's Servers

Here is the single most important thing to understand about Claude Code: it is two completely separate systems pretending to be one.

When you install Claude Code and start chatting with it in your terminal, you might imagine that a tiny AI has moved into your laptop. That is not what has happened. What has actually happened is that a very capable middleman has set up shop on your machine, and it has the AI's phone number.

Your machine runs a TypeScript application built on the Bun runtime. It is roughly 512,000 lines of code.src It handles everything physical: reading your files, running shell commands, searching your codebase with ripgrep, rendering the terminal interface (built with React and a library called Ink), and managing permissions so Claude doesn't accidentally rm -rf your life's work.

Anthropic's servers run the actual AI model โ€” Sonnet, Opus, or Haiku, depending on your configuration. All reasoning, planning, code understanding, and decision-making happens there.docs The model never touches your files directly. It never executes a single command on your machine. It can only ask the local client to do things on its behalf.

The communication between the two happens over HTTPS (TLS-encrypted) via Anthropic's Messages API.docs The model's response streams back as Server-Sent Events, so you see text appearing in real-time rather than waiting for the full response.

Think of it like a Test match. The batsman (the local CLI) is the one at the crease โ€” physically present, playing the shots, running between wickets. The captain sitting in the dressing room (the AI model on Anthropic's servers) is watching the match on a TV feed, sending field placement instructions via walkie-talkie. The captain is the brains of the operation. But the captain never sets foot on the pitch and never touches the ball. The batsman handles all the physical action; the captain handles all the strategy.

YOUR MACHINE Terminal UI React + Ink Query Engine API orchestration Tool System ~40 tools Permissions Risk-classified Local Execution File I/O, Bash, Git, Search, Sandbox Session Store Conversation history, checkpoints, memory Bun runtime ยท TypeScript ยท ~512K LOC ANTHROPIC'S SERVERS Claude Model Sonnet ยท Opus ยท Haiku All reasoning, planning, code understanding โ†’ Generates tool_use decisions โ†’ Writes code and explanations โ†’ Plans multi-step approaches โ†’ Never executes anything locally prompt + context response + tool calls HTTPS

The split architecture: your machine handles execution, Anthropic's servers handle reasoning

512K
lines of TypeScript in the local client
~40
local tools (Read, Edit, Bash, Grep, etc.)
0
lines of AI model code running on your machine
100%
of inference happens on Anthropic's servers

How It Actually Works, Ball by Ball

Claude Code does not just answer questions. It acts โ€” reading files, running commands, editing code โ€” in a continuous loop until the job is done. This loop is the heart of the system.

Here is what happens every time you type a message:

Step 1: The local client assembles the full context โ€” your message, the entire conversation history so far, the system prompt, your project's CLAUDE.md instructions, tool definitions, and any auto-memory. This entire bundle is sent to Anthropic's API as a single request.docs

Step 2: The model processes everything and streams back a response. This response might be plain text ("Here's what I found...") or it might contain tool calls โ€” structured requests like "read the file at src/utils.ts" or "run npm test in the terminal."

Step 3: The local client intercepts each tool call, checks it against the permission system (tools are classified as low, medium, or high risk), and if approved, executes it locally on your machine.docs The model never runs anything โ€” it only asks.

Step 4: The tool result (file contents, command output, search results) is appended to the conversation history.

Step 5: The updated conversation is sent right back to the API. The model sees what happened and decides the next move โ€” maybe another tool call, maybe a final answer.

Step 6: This loop repeats โ€” potentially dozens of times in a single response โ€” until the model produces a reply with no further tool calls. Only then does control return to you.

This is an over in a Test match. The bowler runs in and delivers (prompt sent to API). The batsman reads the delivery and plays a shot (model decides a tool call). The ball races to the boundary rope, a fielder chases it down and throws it back (local client executes the tool and returns the result). The bowler gets the ball back and runs in again (next API call with updated context). Six balls per over, but Claude's overs have no fixed limit โ€” the loop continues until the model declares its innings complete.

THE AGENTIC LOOP Repeats until no more tool calls 1 Assemble context Prompt + history + tools 2 Send to API HTTPS โ†’ Anthropic 3 Model responds Text + tool_use blocks 4 Execute locally Read, Edit, Bash, Grep... 5 Append result Add to conversation 6 Loop or finish More tool calls? โ†’ Step 1 REPEAT = runs on your machine = runs on Anthropic's servers

Each "turn" may involve multiple tool calls โ€” Claude can read, edit, and test in a single response

A key detail: the model can issue multiple tool calls in a single response. If it needs to read three files, it asks for all three at once, and the local client executes them in parallel. This is how Claude can read a file, edit it, run the tests, and respond with the results โ€” all in what feels like a single "turn."

Claude Code can also spawn sub-agents โ€” separate instances with their own isolated context windows. This is how it parallelizes complex tasks: one sub-agent explores the codebase while another researches a library, and neither clutters the main conversation's memory.

What Leaves Your Machine?

This is the question everyone eventually asks, and the answer requires honesty: yes, your code is sent to Anthropic's servers. There is no way around this.

The AI model runs on Anthropic's servers. For it to read your code, understand your project structure, or suggest edits, it must see the code. And "seeing" means the code is transmitted over the network as part of the API request. There is no local model, no on-device inference, no clever trick where the model reasons about your code without actually receiving it.

However, it is not a wholesale upload. Claude Code does not vacuum up your entire codebase and ship it off. It sends only what is needed for the current conversation:

Think of the TV broadcast of a cricket match. The cameras (API requests) show the dressing room captain (the model) what is happening on the pitch. The captain cannot set field placements for a delivery he cannot see. But the cameras are selective โ€” they show the action at the crease, not every vendor in the parking lot. Similarly, Claude sees only the files it explicitly reads, not your entire hard drive.

▲ Sent to Anthropic's servers

  • Your prompts and Claude's responses (the full conversation history)
  • Contents of files that Claude explicitly reads (not all files โ€” only the ones Claude's tools open)
  • Output of shell commands Claude runs (test results, build output, etc.)
  • Your project's CLAUDE.md instructions and auto-memory
  • Tool definitions (so the model knows what tools are available)
  • Telemetry data โ€” usage patterns and latency metrics (no code or file paths)docs

▼ Stays on your machine

  • Your filesystem (files are not uploaded to storage โ€” they're included in API context only when read)
  • All tool execution (bash commands, file edits, git operations run locally)
  • Session files and conversation history (saved locally for resume/fork)
  • Checkpoint snapshots (file state before edits, stored locally for rollback)
  • Permission configurations and settings
  • Files Claude has not read โ€” if Claude never opens a file, its contents never leave your machine
  • Databases, running applications, environment variables (unless you share them in conversation)
YOUR MACHINE All project files Bash execution Session storage Checkpoints Git operations Permissions Read file contents Command output Conversation history + prompts ANTHROPIC'S SERVERS Claude Model Processes context โ†’ generates response Encrypted in transit (TLS) 30-day default retention ZDR available for Enterprise/API = never leaves your machine = sent to Anthropic's servers (encrypted)

Only what Claude reads and the conversation itself are transmitted โ€” everything else stays local

A nuance worth understanding: when Claude reads a file, the file contents become part of the conversation context sent in the API request. They are not uploaded to a separate file store. They exist in the request payload, encrypted in transit via TLS, and are subject to Anthropic's data retention policies (which we'll cover next).docs Once the conversation ends and the retention period passes, those file contents are not persistently stored on Anthropic's side.

Stadium Security: Who Gets in Where

If your code is leaving your machine, the obvious follow-up is: how is it protected? The answer depends on which tier of service you're using.

Think of it as stadium access. General Admission (Free/Pro/Max) gets you into the ground with standard security checks. The VIP Enclosure (Team/Enterprise) adds dedicated security, stricter access controls, and your own private viewing area. The Players' Enclosure (API with Zero Data Retention) is the most restricted โ€” once the match is over, even the CCTV footage is erased.

General Admission

Free / Pro / Max

  • TLS encryption in transit
  • 30-day data retention
  • User choice on training opt-in
  • If training opted in: 5-year retention
  • Standard telemetry enabled
  • No Zero Data Retention option

VIP Enclosure

Team / Enterprise

  • TLS encryption in transit + at rest
  • 30-day default retention
  • No training on data (default)
  • SSO for Enterprise
  • HIPAA-ready with BAA
  • ZDR available (Enterprise)

Players' Enclosure

API / Bedrock / Vertex

  • Zero Data Retention available
  • No training on data (default)
  • VPC-contained (Bedrock/Vertex)
  • Telemetry off by default
  • SOC 2 Type II, ISO 27001
  • BYOK coming H1 2026

Certifications and Compliance

Anthropic holds SOC 2 Type II attestation, ISO 27001:2022 and ISO/IEC 42001:2023 (AI Management Systems) certifications.docs HIPAA compliance is available via Business Associate Agreement. Compliance documentation is available through the Anthropic Trust Center.

What About Training?

This is the question people most care about, and the answer is more nuanced than a flat yes or no:

Locking It Down Further

For maximum privacy, Claude Code supports environment variables that disable non-essential outbound traffic:

DISABLE_TELEMETRY=1
DISABLE_ERROR_REPORTING=1
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Cloud providers like AWS Bedrock and Google Vertex AI offer an additional layer: your API calls stay within your own cloud VPC, and telemetry/error reporting are disabled by default on these platforms.docs

What Your Machine Actually Does (And Eats)

If all the thinking happens on Anthropic's servers, why is Claude Code using 800+ megabytes of your RAM? Fair question.

The local client is not a trivial program. It is a full TypeScript application running on the Bun runtime, rendering a React-based terminal interface, maintaining conversation state, buffering tool results, managing file checksums for rollback, and orchestrating the permission system. All of this takes memory.

Measured baseline: approximately 820 MB of resident memory (RSS) per idle session. Official documentation puts the expected range at 100โ€“2,000 MB depending on what Claude is doing. Reading large files, buffering long command outputs, or spawning sub-agents will push the number higher.

The ground staff at a cricket stadium. They maintain the pitch, manage the scoreboard, operate the floodlights, run the PA system, and keep the crowd fed. Without them, no match happens. But they are not the ones scoring centuries. More ground staff (more RAM) means a better-maintained stadium (smoother experience), but they cannot bat or bowl on your behalf. The quality of Claude's thinking is determined by the model on Anthropic's servers โ€” your RAM just determines whether the local experience stutters or flows.

CLI vs. Desktop App vs. VS Code Extension

Claude Code runs in three different environments, all using the same core engine:

Aspect CLI (Terminal) Desktop App VS Code Extension
Runtime Bun process Electron + Bun engine VS Code + embedded CLI
Memory overhead Lowest Medium (Electron) Medium (VS Code)
Process model 1 main + sub-agents Electron + Bun + sub-agents VS Code + CLI binary + sub-agents
Core engine Identical agentic loop, same tools, same API calls
Extras Full feature set Visual diff, preview, scheduling Inline diff, sidebar, Jupyter

The VS Code extension is architecturally interesting: it embeds the CLI binary and runs a local MCP server that the CLI connects to.docs It is not a reimplementation โ€” it is a bridge. The Desktop app is an Electron shell around the same Bun-based core.docs In all three cases, the agentic loop, tool system, and API communication are identical.

Multiple Sessions

Each Claude Code session runs as a fully independent process. Separate process, separate context window, separate memory. There is no shared state between sessions except your CLAUDE.md, auto-memory files on disk, and โ€” importantly โ€” your API rate limits, which are pooled across all sessions under the same subscription.

With stable versions at ~820 MB each, running 4 simultaneous sessions costs roughly 3.2 GB of RAM โ€” manageable on a 16 GB machine. The practical bottleneck for multiple sessions is usually rate limits, not RAM.

Does More RAM Help?

Mostly no. The quality of Claude's output โ€” its reasoning, code understanding, and suggestions โ€” is determined entirely by the model running on Anthropic's servers. Your local RAM has zero influence on that. The model doesn't run faster because your laptop has 64 GB instead of 16 GB.

Where RAM does matter:

Recommendation: 16 GB is comfortable for single-session use. 32 GB is prudent if you run multiple sessions or use the Desktop/VS Code versions alongside heavy dev tools.

~820 MB
per session baseline (stable versions)
16 GB
recommended for single-session use
32 GB
prudent for multi-session or IDE + Claude

The Scorecard: What the Captain Sees

The context window is the single most important concept for understanding Claude Code's behaviour and limitations. It is the totality of what the model can see on each turn.

Every time the local client sends a request to Anthropic's API, it sends the entire accumulated context: the system prompt, your CLAUDE.md, auto-memory, all tool definitions, every message in the conversation so far, and every tool result. The model does not "remember" anything between turns โ€” it re-reads the full context on every single API call.

The scorecard. It records every ball bowled, every run scored, every wicket taken throughout the innings. The captain in the dressing room studies the full scorecard before each delivery to understand the state of play. But scorecards have a fixed number of pages. When the innings runs long, the scorers start summarising early sessions into compressed notes โ€” "opening partnership of 87 in 22 overs" instead of ball-by-ball detail. That is exactly what context compaction does.

What Fills the Context Window

System
CLAUDE.md
Memory
Tools
Conversation history
Tool results (file contents, command output)
System prompt CLAUDE.md Auto-memory Tool definitions Conversation Tool results

The biggest consumers of context space are tool results (every file Claude reads and every command output) and the conversation history (every message back and forth). The system prompt, CLAUDE.md, and tool definitions are relatively fixed overhead.

Context Compaction

Claude Code currently supports a context window of up to 200,000 tokens per turn. When the accumulated context approaches this limit, the system automatically triggers compaction:

This is why very long Claude Code sessions can sometimes "forget" instructions you gave early on โ€” those instructions may have been compacted away. It is also why the CLAUDE.md file is valuable: it is re-injected on every turn and survives compaction.docs

No Local Indexing

A surprising architectural choice: Claude Code does not build an index of your codebase. No vector database, no embeddings, no background indexing process. Early versions experimented with RAG (Retrieval-Augmented Generation) using a local vector store, but the team found that agentic search โ€” where the model uses Glob and Grep tools to actively explore the codebase โ€” outperformed it significantly. This was confirmed by Boris Cherny, Claude Code's creator.src

The practical implication: every search starts from scratch against the live filesystem. For the vast majority of codebases (under 100K files), this works well and has the advantage of never serving stale results from an outdated index. For truly massive monorepos, it can be slower.

Prompt Caching

Here is an efficiency trick that matters: Anthropic reports a 92% prompt prefix reuse rate for Claude Code sessions, resulting in approximately 81% cost reduction.src Because the beginning of each API call (system prompt, CLAUDE.md, tool definitions, early conversation) is identical to the previous call, the API can cache and reuse the processing of that prefix. You pay full price only for the new content at the end of each turn.

The Technical Terms, Decoded

Every field has its jargon. Here is what the key terms actually mean, stripped of mystique.

Inference

+

The process of running an input through a trained AI model to produce an output. When Claude reads your code and suggests a fix, the "thinking" step is inference. It requires specialised hardware (GPUs/TPUs) and runs on Anthropic's servers, not your machine. Think of it as the model "using" its training โ€” learning happened months ago, inference is applying that knowledge now.

Context Window

+

The total amount of text (measured in tokens) that the model can consider in a single API call. Claude Code uses up to 200K tokens per turn. Everything the model needs to know โ€” your question, the conversation history, file contents, tool definitions โ€” must fit within this window. It is not persistent memory; the model re-reads the full context on every turn.

Tokens

+

The units AI models use to measure text. A token is roughly 3/4 of an English word, or about 4 characters. "Hello world" is 2 tokens. A 500-line source file might be 2,000โ€“5,000 tokens depending on density. Context windows, pricing, and rate limits are all measured in tokens.

Agentic Loop

+

A pattern where the AI model does not just answer a question โ€” it takes actions (reading files, running commands), observes the results, and decides what to do next, in a continuous loop. This is what makes Claude Code different from a chatbot: it can independently investigate a bug, try a fix, run tests, and iterate until the problem is solved.

Tool Use

+

The mechanism by which the AI model requests actions to be performed. Instead of printing "you should run npm test," the model emits a structured tool_use block that says "run this command." The local client then executes it and returns the result. The model decides what to do; the local client does it. This separation is fundamental to Claude Code's architecture.

Bun

+

A JavaScript/TypeScript runtime, similar to Node.js but designed for speed. Claude Code chose Bun over Node.js for faster startup times and built-in TypeScript support. When you see a Claude Code process in your Activity Monitor, it is a Bun process, not a Node.js one. Bun is open-source, created by Jarred Sumner, and written in Zig.

Server-Sent Events (SSE)

+

A web standard for streaming data from a server to a client over HTTP. When Claude's response appears word-by-word in your terminal, that is SSE at work โ€” the server sends chunks of the response as they are generated, rather than waiting for the full response to be complete. This is what makes Claude Code feel responsive even when generating long answers.

Compaction

+

The process of condensing the conversation context when it approaches the context window limit. Claude Code automatically summarises older parts of the conversation and discards detailed tool outputs that have already been processed. Think of it as the difference between a ball-by-ball commentary and a session summary โ€” the key information is preserved, but the granular detail is compressed.

Zero Data Retention (ZDR)

+

A data handling mode where Anthropic does not store your API inputs or outputs at rest after the response is returned. Available for Enterprise and API (commercial) plans. Even under ZDR, content flagged for usage policy violations may be retained for up to 2 years. ZDR is not available on consumer plans (Free, Pro, Max).docs

SOC 2 Type II

+

An auditing standard that evaluates how a company manages customer data, specifically examining security, availability, processing integrity, confidentiality, and privacy controls. "Type II" means an independent auditor has verified that these controls were not only designed well but also operated effectively over a period of time (typically 6โ€“12 months). It is the most widely recognised trust certification in cloud computing.

MCP (Model Context Protocol)

+

An open standard (created by Anthropic) that lets AI models connect to external tools and data sources through a standardised interface. In Claude Code, MCP servers can provide additional tools beyond the built-in ~40 โ€” for example, connecting to databases, cloud services, or custom APIs. The VS Code extension uses MCP internally to bridge between VS Code and the CLI engine.

ripgrep (rg)

+

A blazing-fast text search tool written in Rust. When Claude Code searches your codebase (the Grep tool), it uses ripgrep under the hood, not the standard Unix grep. ripgrep is significantly faster, respects .gitignore files by default, and handles Unicode correctly. Claude Code bundles its own copy via the @vscode/ripgrep package.

Prompt Caching

+

An optimisation where the API reuses the processing of repeated prompt prefixes. Since the beginning of each Claude Code API call (system prompt, CLAUDE.md, tool definitions, early conversation) is identical to the previous call, the API can skip re-processing that prefix. Anthropic reports 92% prefix reuse in Claude Code sessions, resulting in ~81% cost reduction.

Go Deeper

The sources behind this article, plus some genuinely useful reads if you want to understand the internals further.

Official Docs

How Claude Code Works

Anthropic's own explanation of the agentic loop, tool system, and context management. The single best primary source for understanding the architecture.

Official Docs

Security Model

Sandboxing, permission levels, file access restrictions, and how Claude Code protects your system from unintended actions. Covers both macOS seatbelt and Linux bubblewrap.

Official Docs

Data Usage & Privacy

What data is sent, how long it is retained, training policies by tier, and how to disable telemetry. Essential reading if you work with sensitive codebases.

Engineering Blog

Claude Code Sandboxing

Anthropic's engineering team on how they sandbox bash commands using OS-level primitives โ€” macOS seatbelt profiles and Linux bubblewrap containers.

Analysis

Why Claude Code Doesn't Index Your Codebase

Vadim's analysis of Claude Code's search strategy: why agentic search with ripgrep outperformed RAG with a local vector database, and the prompt caching economics that make it viable.

Official Docs

Authentication & Credentials

OAuth, API keys, cloud provider credentials (Bedrock, Vertex, Foundry), and how credentials are stored on each platform โ€” macOS Keychain, Linux file permissions, etc.

Trust Center

Anthropic Trust Center

SOC 2 Type II reports, ISO 27001 and 42001 certifications, HIPAA documentation, and compliance artifacts. The authoritative source for enterprise security evaluation.

Open Source

Claude Code on GitHub

The official repository. Issues, discussions, release notes, and the npm package. Good for tracking known bugs (like memory regressions) and upcoming features.

Official Docs

Zero Data Retention (ZDR)

The full details on ZDR: which plans and features are eligible, what exceptions exist for policy violations, and how to enable it for your organisation.

Official Docs

Claude Code Overview

The starting point for everything: installation, system requirements (4 GB RAM minimum, 16 GB recommended), supported platforms, and getting started guides.