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?
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.
The split architecture: your machine handles execution, Anthropic's servers handle reasoning
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.
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.
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.
CLAUDE.md instructions and auto-memoryOnly 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.
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.
Free / Pro / Max
Team / Enterprise
API / Bedrock / Vertex
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.
This is the question people most care about, and the answer is more nuanced than a flat yes or no:
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
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.
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.
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.
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.
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.
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.
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
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.
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.
Every field has its jargon. Here is what the key terms actually mean, stripped of mystique.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
The sources behind this article, plus some genuinely useful reads if you want to understand the internals further.
Anthropic's own explanation of the agentic loop, tool system, and context management. The single best primary source for understanding the architecture.
Sandboxing, permission levels, file access restrictions, and how Claude Code protects your system from unintended actions. Covers both macOS seatbelt and Linux bubblewrap.
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.
Anthropic's engineering team on how they sandbox bash commands using OS-level primitives โ macOS seatbelt profiles and Linux bubblewrap containers.
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.
OAuth, API keys, cloud provider credentials (Bedrock, Vertex, Foundry), and how credentials are stored on each platform โ macOS Keychain, Linux file permissions, etc.
SOC 2 Type II reports, ISO 27001 and 42001 certifications, HIPAA documentation, and compliance artifacts. The authoritative source for enterprise security evaluation.
The official repository. Issues, discussions, release notes, and the npm package. Good for tracking known bugs (like memory regressions) and upcoming features.
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.
The starting point for everything: installation, system requirements (4 GB RAM minimum, 16 GB recommended), supported platforms, and getting started guides.