How Claude Code Works
📚 Series Navigation: The previous article 02 · Installation and Usage guided you to install and run Claude Code. This article removes the lid to see clearly how it actually works—why it can read code, modify files, and run commands by itself, rather than just chatting.
When using Claude Code for the first time, you will often encounter a conversation like this—
You: "Why did this test fail?" Claude: "Let me run the test suite to see." (Starts running command) Claude: "The error says
validateEmailreturned undefined, I'll go check this function." (Reads the file) Claude: "Found it, a return is missing here. I'll modify it, and then re-run the tests to confirm." (Modifies it, and runs it again) Claude: "Tests passed."
Seeing this, it's easy to be a little confused: With just one sentence asked, how did it run commands, read files, modify them, and verify the results all by itself?
Frankly speaking, this is the biggest difference between Claude Code and a normal AI chat box. A chat box will only "reply with a paragraph of text," while Claude Code will do things itself. Behind this is a fixed working mechanism, which we will explain thoroughly today.
After reading this article, you will get:
- Understand Claude Code's "agentic loop" with one picture—the three actions it repeats for everything it does
- Figure out what the 5 categories of "tools" in its hands can do, and how it decides which one to use
- Know exactly what it can and cannot see on your computer (related to security)
- A small experiment you can run to see it complete an entire loop with your own eyes
01 Agentic Loop: Think → Act → Observe
Conclusion first: Whenever Claude Code does any work, it is repeating three actions—collecting context, taking action, verifying results. Officially, this mechanism is called the "agentic loop".
In more colloquial terms: Think → Act → Observe.
- Think (collect context): First figure out the situation—read relevant files, check errors, check git status
- Act (take action): Do the work—modify code, run commands, create files
- Observe (verify results): Check if what was just done is correct—run tests, check output, if incorrect, do another round
Analogy: A reliable mechanic. You drive your car into the shop and say "the steering wheel shakes," the mechanic won't dismantle it immediately. He will first look around, test drive a bit (Think), then use the wrench (Act), and after fixing it, drive a bit to confirm it doesn't shake (Observe). If it still shakes, he goes back to the first step to re-check. Claude Code is just such a mechanic, except what it repairs is your code.
Returning to the conversation at the beginning, you will understand it by comparing:
| What Claude said | Which step in the loop it corresponds to |
|---|---|
| "Let me run the test suite" | Think (collect context) |
| "Error says undefined, I'll go check this function" | Think (continue collecting) |
| "A return is missing here, I'll modify it" | Act (take action) |
| "And then re-run tests to confirm" | Observe (verify results) |
| "Tests passed" | Loop ends |
It strings these three steps into a chain, and the result of one step determines what the next step will do. Fixing a bug might loop several rounds, asking "what does this code mean" might only require the "Think" step. How many rounds it loops is determined by the task complexity, it is not hardcoded.
The picture above is the circle Claude Code turns every time it works: from "Think" to "Act" to "Observe", and if unsatisfied, it turns from "Observe" back to "Think" for another round—you can press Esc at any time to stop it.
There is a key point here that many people do not realize: You are also part of this loop. If it deviates, you can interrupt and correct it at any time—this will be discussed in detail in the next section.
What drives this loop are two things: the model is responsible for "Thinking", tools are responsible for "Acting" and "Observing".
The model is Claude's brain—Sonnet is sufficient for daily programming, Opus has stronger reasoning and is suitable for complex architectures. You can switch at any time by entering /model in the conversation, or claude --model sonnet when starting.
💡 One-sentence summary: Claude Code is not "replying with a paragraph of text," but turning the "Think→Act→Observe" circle until the job is done, this is the essential difference between it and a chat box.
02 You Are Also in the Loop: Interrupt at Any Time
The end of the previous section mentioned: you are also a part of this loop. Let's expand on this. Normal AI chat is "you ask a sentence, it answers a paragraph, round ends". Claude Code is different—when it is running in a loop by itself, you don't have to wait idly, you can intervene at any time.
For example, letting it refactor a module, seeing it going astray and about to overhaul a bunch of files, directly press Esc, it stops immediately, and running commands are also canceled. Then add "don't touch that file, only modify this function," and it will follow the new instruction.
There are two ways to interrupt, the differences must be distinguished:
| Operation | Effect | When to use |
|---|---|---|
Press Esc | Stop immediately, the running tool call is canceled, waits for your next instruction | It has gone astray, what it's doing is wrong, quickly stop it |
Type + Enter | Does not interrupt current operation, sends a supplementary sentence, it will read it after finishing its current task | Just want to add context, give a reminder, not urgently stopping |
You don't need to hold in a "perfect prompt". Give a general direction first, see it work, and correct if it's wrong—this is a conversation, not a one-time command.
This is the exact original wording from the official documentation, especially worth remembering. When just starting, people always want to "say all the requirements in one sentence," holding it in for a long time. In fact, it's not necessary: throw a general direction, call stop if it does wrong, iterating is much faster than holding a big move.
💡 One-sentence summary: It works autonomously, but always listens to your command—
Escemergency stop, typing to supplement, the steering wheel is always in your hands.
03 Tools: The Reason It Can Actually Act
The previous section said the model is responsible for "Thinking". So what do "Act" and "Observe" rely on? Tools.
This is the most important sentence to remember for Claude Code: Without tools, Claude can only reply to you with text; with tools, it can actually read your code, modify your files, and run your commands.
Analogy: An assistant wearing a smart wristband. An assistant who can only talk can only give ideas; equip him with devices that can open doors, type, and look up information, and he can truly get things done for you. Tools are Claude Code's "hands".
Officially, built-in tools are divided into 5 major categories. I will list them for you in plain language—
| Tool Category | What it can do | What operation you usually do |
|---|---|---|
| File Operations | Read files, modify code, create files, rename, reorganize | Opening, typing, saving in the editor |
| Search | Find files by filename, use regex to search content, search the entire codebase | You pressing Ctrl+F or grep |
| Execution | Run shell commands, start servers, run tests, use git | You typing a command in the terminal and pressing enter |
| Network | Search web pages, grab documentation, look up error info | You open a browser to search an error |
| Code Intelligence | See type errors and warnings, go to definition, find references | IDE's "Go to Definition", "Find References" |
⚠️ Note: The 5th category "Code Intelligence" requires additionally installing Code Intelligence Plugins, the first 4 categories work out of the box. Refer to the official documentation.
Then how does it decide which tool to use? You don't specify it, the model chooses itself based on your words and current progress.
Take an official example, you say "fix the failing test", internally it roughly goes like this:
- Run the test suite, see which one failed — used Execution
- Read the error output — Execution
- Search related source files — Search
- Read these files to understand the logic — File Operations
- Modify files to fix the bug — File Operations
- Run the test again to verify — Execution
See it? These 6 steps are the unrolling of the "Think→Act→Observe" loop at the tool level. Each time a tool is used, a bit of new information is retrieved, fed to the model to decide the next step—this is how the loop spins.
There is a very typical scenario: asking it to "sort out the directory structure" for an old project without documentation. It doesn't need you to feed it any files, it will ls itself, grep keywords itself, read seven or eight files, and finally draw a structure diagram. No specific file was specified throughout the process—this is what the official calls "delegate, don't dictate": give a direction, it figures out the details itself.
As for Skill, MCP, Hook, Subagent, etc.—they are extension layers built on top of these 5 categories of built-in tools, enabling Claude to know more and connect to more external services. This series will explain them article by article later, just know they exist for now.
💡 One-sentence summary: Tools are Claude Code's "hands", the 5 categories each manage their own part; which one to use and how many times, it decides itself, you just state the goal.
04 What It Can See on Your Computer
This section is related to security, it must be stated clearly. Many people wonder when using it for the first time: Did it search through my entire hard drive and send it away? No.
Remember one sentence first: Claude Code's "vision" basically equals what you can touch with the terminal in that directory. Wherever you type claude, its activity scope is centered there.
According to the official documentation, when you run claude in a directory, it can access:
- Your project: Files in the current directory and subdirectories (files elsewhere need you to give permission to be touched)
- Your terminal: Any command you can run—build tools, git, package managers, scripts. Whatever the command line can do, it can do
- Your git status: Current branch, uncommitted changes, recent commit history
- Your
CLAUDE.md: The project-specific manual you wrote, it reads it every session (this file will be discussed in a separate article later) - Your configured extensions: MCP, Skill, Subagent, etc.
Precisely because it can see the entire project, and not just the single file you currently have open, it can coordinate across files—you say "fix login bug", it can search out several related files, modify them together, and then run tests to verify. This is fundamentally different from inline completion plugins that only look at the current file.
Then how is security guaranteed? Two gates—
The first gate: Checkpoints, equivalent to game saves. Before modifying any file, it will take a snapshot of the current content. If it breaks something, pressing Esc twice consecutively when the input box is empty (or entering /rewind) will pop up a "rewind menu", select "Restore code" to revert the file to before modification; you can also directly say "undo the modification just now".
Checkpoints only govern files modified by Claude's editing tools—modifications by bash commands, and external side effects are not included. Operations like databases, APIs, online deployments that "can't be taken back once poured out" cannot be saved—so Claude will ask you first before running such commands with external impact.
There is a commonly stepped-on pitfall here: sometimes it modifies five or six files, and after reading it you feel the direction is totally wrong. In the past, you'd have to manually git checkout to rollback one by one, now press Esc twice, select "Restore code" in the popup menu—all five files revert to before modification in unison, clean and neat. With this trick, letting it modify code is not so scary.
The second gate: Permission modes, equivalent to whether an intern asks you before acting. Press Shift+Tab to cycle switch:
| Permission Mode | Claude's Behavior |
|---|---|
| Default | Asks you before modifying files or running commands |
| Auto-accept edits | Does not ask for file modifications and common file commands (like mkdir, mv), still asks for other commands |
| Plan Mode | Can read files and run exploratory commands, but does not edit source code; gives you a plan first, acts only after you approve |
| Auto mode | Evaluates all actions with a background safety check (Experimental, currently research preview, may change) |
The most worthwhile habit to develop is to use Plan Mode: for complex tasks, press Shift+Tab twice to enter it, let it "only analyze, propose a plan, don't act", go through the plan, modify it, and let it execute after confirmation. This can avoid many reworks of "direction was wrong, half modified"—looking at the blueprint before construction saves much more trouble than building and modifying at the same time.
Annoyed that it asks every time? You can add trusted commands (like npm test, git status) to the whitelist in the project's .claude/settings.json, and it won't ask later. Configuration details will be discussed in a separate article later.
💡 One-sentence summary: Its vision ≈ your terminal permission in that directory; Checkpoints manage "can undo if broken", permission modes manage "whether to ask before acting"—with the two gates down, feel at ease to let go and use it.
05 Hands-on: See It Complete a Full Loop With Your Own Eyes
Just reading principles won't stick in memory, run a minimal experiment, see it "Think→Act→Observe" turn a circle with your own eyes. This experiment does not depend on any ready-made project, creating an empty folder will do.
First step: Create an empty directory, enter and launch Claude Code.
Run in terminal (Mac / Linux; Windows users just replace mkdir -p with mkdir in PowerShell):
mkdir -p ~/cc-demo && cd ~/cc-demo
claudeSecond step: After entering, first switch to Plan Mode to see how it "Thinks".
Press Shift+Tab twice, the bottom of the interface will prompt that you have entered Plan Mode. Then throw this sentence to it:
Help me write a Python script add.py, with a function add(a, b) returning the sum of two numbers,
then write a few test cases to verify it, finally run the test. Give me a plan first, don't just act.Expect to see: It will not create the file immediately, but first return a plan to you, roughly—
Plan:
1. Create add.py, implement add(a, b)
2. Create tests (using assert or pytest)
3. Run tests, confirm all passed
Should I begin?This is "Thinking"—it cleared its thoughts before acting. Note that it stopped and waited for your approval, this is the characteristic of Plan Mode.
Third step: Approve, see it "Act" + "Observe".
Reply "Yes, start". Then you will see it sequentially:
- Create file (file operation tool) — may pop up a permission confirmation first, you press agree
- After writing, run tests (execution tool), for example executing
python add.pyorpytest - Paste the test output to you, expected is similar to:
Tests passed: add(2, 3) == 5 ✓ add(-1, 1) == 0 ✓ add(0, 0) == 0 ✓Here, you have completely seen a loop: Think (propose plan) → Act (create file, write code) → Observe (run test and report result).
Fourth step (optional): Deliberately create a "re-loop".
Tell it: "Change add to subtraction, but keep the function name the same, then re-run the tests."
You will see it modify the code, then run tests—if the test assertion is still addition, the test will fail, it will discover the failure itself, turn back and modify again. This is the essence of the loop: Seeing something wrong, automatically doing another round.
Every beginner should run this experiment once. Compared to reading the four words "agentic loop" ten times, seeing it stop to propose a plan, then act, then verify with your own eyes, will make you understand much faster.
💡 One-sentence summary: Running this minimal experiment once, you will see "Think→Act→Observe" turning a circle with your own eyes—especially the part where it discovers mistakes itself and automatically does another round.
06 Summary
This article explained one thing clearly: Why Claude Code can work by itself.
Review the core:
| Key Point | Remember in One Sentence |
|---|---|
| Agentic Loop | Think→Act→Observe, turn circle until done; this is the essential difference between it and a chat box |
| Model + Tools | Model thinks, tools act and observe |
| 5 Categories of Tools | Files / Search / Execution / Network / Code Intelligence, it picks which one to use |
| What it can see | ≈Your terminal permission in that directory, can coordinate across files |
| Two Security Gates | Checkpoints (undo if broken) + Permission modes (whether to ask before acting) |
You should now be able to understand what is happening on the screen when Claude Code runs a task—every file it reads, every command it runs, is a step in the loop; you also know how to use Esc for emergency stop, use Plan Mode to look at the plan first, and rely on checkpoints to let it modify with peace of mind.
Understanding this mechanism, your mindset when using it will be completely different: it's not a wishing well, but a partner that can think, act, and check by itself—your job is to give direction, set acceptance criteria, and pull it back when it goes astray.
Next article 04 · API Config: Claude Code is installed, the principles are understood, but it needs to connect to a model to truly work. The next article guides you to configure the API—once this step is done, the loops and tools learned earlier can run.