How Claude Code Works
Understanding what happens under the hood makes you a far better user of Claude Code. When you know how information flows between your terminal, your files, and the AI model, you write better prompts and avoid common mistakes that frustrate beginners.
The Big Picture in One Diagram
┌──────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ Your │ │ Claude Code │ │ Anthropic │ │ Terminal │◄────►│ (local tool) │◄────►│ AI Model │ │ │ │ │ │ (on the internet│ │ You type │ │ Reads files │ │ via API) │ │ requests │ │ Runs commands │ │ │ │ See results │ │ Writes files │ │ Generates text │ └──────────────┘ └─────────────────┘ └──────────────────┘ Everything lives This runs on This thinks and here in your your machine responds terminal
Claude Code has two distinct parts. One part runs on your computer — it is the local tool that reads your files and talks to your terminal. The other part is the AI model, which runs on Anthropic's servers and does the actual thinking. Your local tool collects context from your machine, sends it to the model, receives a response, and acts on your behalf.
Step-by-Step: What Happens When You Send a Message
Step 1: You type a request
┌─────────────────────────────────────┐
│ You: Add a search bar to the header │
└──────────────┬──────────────────────┘
│
▼
Step 2: Claude Code gathers context
┌──────────────────────────────────────────────────────┐
│ Reads: header.html, styles.css, app.js │
│ Checks: recent conversation history │
│ Looks at: any files you mentioned earlier │
└──────────────┬───────────────────────────────────────┘
│
▼
Step 3: Sends a package to the AI model
┌──────────────────────────────────────────────────────┐
│ Package contains: │
│ • Your request ("Add a search bar to the header") │
│ • Contents of relevant files │
│ • Conversation history (last N turns) │
└──────────────┬───────────────────────────────────────┘
│
▼
Step 4: AI model generates a response
┌──────────────────────────────────────────────────────┐
│ Model decides: write code? run a command? ask a │
│ clarifying question? explain something? │
└──────────────┬───────────────────────────────────────┘
│
▼
Step 5: Claude Code acts on the response
┌──────────────────────────────────────────────────────┐
│ Shows you a diff of proposed changes │
│ Asks permission before editing files │
│ Runs any shell commands after you approve │
└──────────────────────────────────────────────────────┘
What Is the Context Window
The AI model does not have a permanent memory. Every time Claude Code sends a package to the model, it must include all the information the model needs to give a useful answer. That package has a size limit called the context window.
Picture a physical desk. The context window is the desk surface. You can only spread so many papers on a desk at once. When the desk is full, you have to remove some papers before adding new ones. The AI model works the same way — it can only "see" what fits on the desk right now.
CONTEXT WINDOW (the AI's working desk) ┌─────────────────────────────────────────────────────────┐ │ │ │ [Your current message] [File: app.js — 200 lines] │ │ │ │ [Chat history — last 10 turns] │ │ │ │ [File: database.py — 150 lines] │ │ │ │ [File: README.md — 80 lines] [████░░░░░░░░] │ │ 70% full │ └─────────────────────────────────────────────────────────┘ When it fills up: old history drops off, large files get summarized, or you start a fresh conversation.
This is why long conversations about very large codebases sometimes produce answers that seem to forget earlier details. The model is not being careless — it literally cannot see information that fell off the desk. Topic 12 covers context management strategies in full.
How Claude Code Reads Your Files
Claude Code reads files in the directory where you launched it. It does not automatically read every file in your project. It reads files that are relevant to your request — determined by file names you mention, import chains in code, and its own judgment about what matters.
Your project folder structure my-app/ ├── src/ │ ├── app.js ← Claude reads this when you mention "app" │ ├── auth.js ← Claude reads this when you say "login" │ └── utils.js ← Claude reads this if app.js imports it ├── tests/ │ └── auth.test.js ← Claude reads this when you say "tests" ├── package.json ← Claude reads this to understand dependencies └── README.md ← Claude reads this for project overview
You can always tell Claude Code exactly which file to look at. Saying "look at src/auth.js and tell me what the signIn function does" gives a precise, reliable result every time.
How Claude Code Runs Commands
When Claude Code needs to run a shell command — installing a package, running tests, creating a file — it shows you the command first and waits for your approval. This permission step is not optional and cannot be removed. It protects your system from unintended changes.
Claude Code proposes a command ┌─────────────────────────────────────────┐ │ I need to install the date library. │ │ │ │ Command: npm install date-fns │ │ │ │ Allow? [y/n/edit] │ └─────────────────────────────────────────┘ You press y → command runs in your terminal You press n → command is skipped You press e → you can edit the command first
How Claude Code Stays Up to Date with Your Project
Claude Code does not watch your files in real time. It reads a file when it becomes relevant to the current task. If you edit a file in your text editor and then ask Claude Code about it, Claude Code reads the updated version — it always reads from disk, not from a cached copy.
This also means two things to be aware of: Claude Code sees changes other tools made to your files, and it does not track changes you made while it was not involved. Always check the diff Claude Code proposes against what you already changed manually.
Where Claude Code Stores Its Memory
Two types of "memory" in Claude Code ┌─────────────────────────────────────────────────────┐ │ SESSION MEMORY (temporary) │ │ • The current conversation │ │ • Lost when you close the session │ │ • Stays as long as the context window allows │ ├─────────────────────────────────────────────────────┤ │ CLAUDE.md FILES (permanent) │ │ • A file you create in your project │ │ • Claude Code reads it at the start of every │ │ session in that project │ │ • Holds project rules, preferences, and context │ │ • You write and maintain this file yourself │ └─────────────────────────────────────────────────────┘
The CLAUDE.md file is one of the most powerful and underused features of Claude Code. You write your project's rules, naming conventions, architecture notes, and any other guidance in this file. Every session starts with Claude Code automatically reading it, so you never have to repeat yourself.
Key Points
- Claude Code has two parts: a local tool on your machine and an AI model on Anthropic's servers.
- Every message you send triggers a package of context — your files, your message, and your conversation history — sent to the model.
- The context window limits how much the model can see at once — it is a desk with a finite surface area.
- Claude Code reads files on demand, not continuously — it always reads the latest version from disk.
- Every shell command requires your explicit approval before it runs.
- A CLAUDE.md file in your project acts as permanent memory across sessions.