How Claude Code Works
Claude Code is not a chatbot. It is an agent — a loop that reads your project, makes decisions, runs tools, and repeats until the job is done. This lesson covers what happens between pressing Enter and seeing the result on disk.
The agent loop
Every time you type a message, Claude Code runs the same loop. It does not stop after one step — it keeps going until the task is complete or it needs to ask you something.
Receive your message
You type a plain-English instruction. Claude reads it along with open files, conversation history, and CLAUDE.md if one exists.
Plan the steps
Claude decides what needs to happen. For 'add a login page', it might plan: read existing auth setup, write a component, update the router, write a test.
Call a tool
Claude picks one tool — read a file, write a file, run a shell command, or search the web — and executes it. One tool at a time.
Read the result
Tool output returns to the context window. Claude reads file contents, command output, or error text and decides what to do next.
Repeat or finish
If there is more to do, go back to step 3. If the task is complete, Claude writes a summary. If something is unclear, it pauses and asks you.
The context window
Everything Claude "knows" during a session lives in the context window — a sliding buffer of text. Think of it as short-term memory.
| Layer | What it contains | Size |
|---|---|---|
| System prompt | Built-in instructions about how Claude Code should behave | ~2k tokens |
| CLAUDE.md | Your project guide — conventions, architecture notes, commands | varies |
| Conversation | Your messages, Claude replies, and tool call results | grows |
| File reads | Contents of files Claude has read this session | grows |
| Shell output | Stdout/stderr from commands — test results, lint output, errors | grows |
/clear or /compact.Built-in tools
Claude Code has a fixed set of built-in tools. Each maps to something real on your machine.
Read
Reads file contents before editing so Claude never overwrites blindly.
Read(src/app/page.tsx)Read(package.json)Write
Creates or overwrites a file. This is how Claude changes your code.
Write(src/utils/auth.ts, ...)Write(.env.example, ...)Search / Grep
Finds patterns across the codebase — function usage, bug locations.
Grep('useAuth', src/)Glob('**/*.test.ts')Bash / Shell
Runs shell commands — npm install, git status, test suites, builds.
npm testgit diff HEAD~1npx tsc --noEmitWeb Search
Looks up docs, error messages, or package APIs when the answer is not in your repo.
Search('Next.js App Router metadata')TodoRead / TodoWrite
Tracks multi-step progress with a persistent task list.
TodoWrite([{title: 'Add auth', ...}])A simple example, step by step
You type one sentence. Here is what Claude Code does behind the scenes.
| Tool | Action | Result |
|---|---|---|
| Grep | Search for existing price or currency utilities | No formatPrice function in src/ |
| Read | Read src/utils/index.ts for existing util patterns | Named exports, TypeScript strict mode |
| Write | Write formatPrice helper to src/utils/currency.ts | Created src/utils/currency.ts |
| Bash | Run npx tsc --noEmit to check for type errors | No errors. Build clean. |
The file Claude wrote
What Claude does not do
Knowing the limits helps you avoid surprises.
| Assumption | Reality |
|---|---|
| Keeps memory between sessions | Context is blank when you reopen. Use CLAUDE.md to persist project knowledge — it is re-read at session start. |
| Runs in the background | Claude only acts when you send a message. It does not watch files unless you set up a Hook. |
| Guesses when stuck | If Claude hits ambiguity or an unsafe decision, it pauses and asks rather than silently breaking something. |
| Has internet access by default | Web search is a tool Claude can call when needed. Your code is not sent externally unless a tool does so. |
Before you continue
- Claude Code runs an agent loop: plan, tool call, read result, repeat.
- Session knowledge lives in the context window — system prompt, CLAUDE.md, files, and output.
- Built-in tools: Read, Write, Search, Bash, Web, and Todo.
- Claude reads your project and matches conventions before writing.
- Next: the .claude/ directory and project config files.
What's Next
The agent loop is how Claude Code thinks. The next lesson maps out the .claude/ directory memory files, skills, and project config.