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 explains exactly what happens between the moment you press Enter and the moment the result appears on disk.
The Big Picture
Every time you type a message, Claude Code runs the same loop. It does not stop after one step — it keeps going until either the task is complete or it needs to ask you something.
The Agent Loop
Receive your message
You type a plain-English instruction. Claude Code reads it along with everything in your context window — open files, conversation history, and the CLAUDE.md project guide if one exists.
Plan the steps
Claude decides what needs to happen. For a task like 'add a login page', it might plan: read the existing auth setup, write a new 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. It only calls one tool at a time.
Read the result
The tool output comes back into the context window. Claude reads it — a file's contents, command output, 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 final summary reply. If it hit something unexpected, 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.
Context window contents (single session)
System prompt
Built-in instructions from Anthropic about how Claude Code should behave
~2 kCLAUDE.md
Your project guide — coding conventions, architecture notes, commands to use
variesConversation so far
Your messages + Claude's replies + every tool call result in this session
growsFile reads
Contents of files Claude has read during this session — added as they are read
growsShell output
Stdout/stderr from any commands Claude ran — test results, lint output, errors
grows/clear or /compact.The Built-in Tools
Claude Code has a fixed set of tools it can call. These are not plugins — they are built in. Each tool maps to something real on your machine.
Read
Reads the full contents of a file. Claude uses this before editing so it never overwrites something blindly.
Read(src/app/page.tsx)Read(package.json)Write
Creates or overwrites a file with new contents. This is how Claude actually changes your code.
Write(src/utils/auth.ts, ...)Write(.env.example, ...)Search / Grep
Searches for patterns across your codebase. Useful for finding where a function is used or where a bug might be.
Grep('useAuth', src/)Glob('**/*.test.ts')Bash / Shell
Runs a shell command — npm install, git status, running your test suite, checking a build. This is the most powerful tool.
npm testgit diff HEAD~1npx tsc --noEmitWeb Search
Looks up documentation, error messages, or package APIs on the web. Used when the answer is not in your codebase.
Search('Next.js App Router metadata')TodoRead / TodoWrite
Reads and updates a persistent task list so Claude tracks its own progress across multi-step work.
TodoWrite([{title: 'Add auth', ...}])A Simple Example, Step by Step
You type one sentence. Here is what Claude Code actually does behind the scenes.
What Claude does internally
Search for existing price or currency utilities
→ No existing formatPrice function found in src/
Read src/utils/index.ts to understand the existing util pattern
→ Found: export functions use named exports, TypeScript strict mode
Write formatPrice helper to src/utils/currency.ts
→ Created src/utils/currency.ts
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.
✕ It does not keep memory between sessions
When you close Claude Code and reopen it, the context window is blank. Use CLAUDE.md to persist project knowledge — that file is always re-read at session start.
✕ It does not run in the background
Claude Code only acts when you send it a message. It does not watch files or trigger on events unless you set up a Hook (covered later in the course).
✕ It does not guess when it is stuck
If Claude hits an ambiguity or a decision it cannot make safely, it pauses and asks you rather than guessing wrong and silently breaking something.
✕ It does not have internet access by default
Web search is a tool Claude can call — but only when it decides a web lookup is needed. It does not send your code to external services unless you or a tool explicitly does so.
What You Learned
- ✅Claude Code runs an agent loop — plan, tool call, read result, repeat.
- ✅Everything Claude knows lives in the context window for that session.
- ✅It has six built-in tools: Read, Write, Search, Bash, Web, and Todo.
- ✅It reads your project first and matches your conventions before writing.
- →Next: Permission modes — how to control exactly which tools Claude can run without asking.
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.