D1 · The agentic loop and what Claude can actually read (/context)

No configuration tricks in this lesson. It answers just two questions: how Claude Code gets a task done (the agentic loop), and what it can and cannot read while doing it (the context window). At the end, the /context command turns the second question into something you can see with your own eyes.

Why this lesson comes today

Our takeThe two most common newcomer frustrations with Claude Code — "why doesn't it know this file exists in my repo" and "why did it forget what I told it last session" — are not the model falling short. They come from not knowing what it can read. Once that clicks, every later lesson follows naturally:

• D2 The context window & prompt caching expands on what each part of today's "window layers" diagram costs;
• D3 Permission modes & sandboxing governs whether the "act" step of the loop can run automatically;
• D4 CLAUDE.md & rules solves exactly the "I have to re-explain everything every session" problem.

So on day one, we only lay the foundation.

Core concepts, explained

One loop: gather context → take action → verify results

OfficialGive Claude a task and it works in three phases: gathering context, taking action, and verifying results. The three phases are not a fixed pipeline — they interleave. Claude advances by calling tools the whole way: searching files to understand the code, editing files to make changes, running tests to check its own work. Whatever a tool call returns feeds back into the loop and shapes the next step, chaining dozens of actions with self-correction along the way until the task is done.

OfficialYou are in the loop too: press Esc at any moment to stop Claude immediately, or simply type a follow-up and hit Enter — it will read it once the current action finishes and adjust its next step accordingly.

OfficialTwo parts drive the loop: the model does the reasoning, and tools do the acting. Without tools, Claude can only produce text; with them, it can read code, change files, and run commands. Claude Code itself is the "agentic harness" wrapped around the model — it supplies the tools, context management, and execution environment. The built-in tools fall into roughly five groups:

OfficialThe official example: you say "fix the failing tests", and Claude might run the tests to see which fail → read the error output → search for the relevant source files → read them to understand the code → edit a fix → run the tests again to verify. That is the loop in motion.

Another way to put it: a pair programmer who only sees the desk

Our takeThink of Claude as a highly capable pair programmer who can only see the materials spread out on the desk. The desk is the "context window". It has not memorized your repository; to look at a file it has to reach for it (call a tool), and only once the content lands on the desk does it "see" it. The desk is a limited surface, and a full desk needs clearing (that is D2's topic). Understand the desk and you understand most of this course: CLAUDE.md, skills, and subagents — everything that comes later — are really answers to "what should live on the desk permanently, and what should be fetched only when needed".

What it can and cannot read each turn

OfficialIn the directory where you run claude, it can access: project files in that directory and its subdirectories (other locations need your approval), any command your terminal can run, git state (current branch, uncommitted changes, recent commits), CLAUDE.md, auto memory (the first 200 lines or 25KB of MEMORY.md, loaded at the start of every session), and the extensions you have configured (MCP, skills, subagents, and so on).

OfficialWhat actually goes into the context window on each request: system instructions, CLAUDE.md, auto memory, loaded skills, the conversation history, and the file contents and command outputs it has read.

Two of the most common misconceptions, cleared up right now:

• Our takeMisconception 1: "Claude has already read my whole repo." In reality, "can access" is not "has read" — it searches and reads on demand, and only what it has read enters the window. How to check: ask about a detail in a file it has not read, and you will see it call a search or read tool first instead of answering directly.
• OfficialMisconception 2: "It still remembers what I said last session." The official docs state it plainly: sessions are independent, and every new session starts from a fresh, blank context with no prior conversation history. To carry information across sessions, use auto memory or persistent instructions you write into CLAUDE.md (covered in D4).

OfficialThe window fills up as you work. When Claude Code nears the limit it compacts automatically: first it clears older tool outputs, and if that is not enough it summarizes the whole conversation — your request and the key code are preserved, but detailed instructions from early in the conversation may be lost. Hence the official advice: put persistent rules in CLAUDE.md instead of relying on conversation history. Details wait for D2.

Inspecting the window with /context

Official/context draws the current context usage as a colored grid and offers optimization advice: which tools are eating context, whether memory has bloated, capacity warnings. When the conversation exceeds the window limit, the output also shows how far over you are and which command frees space (this warning requires Claude Code v2.1.216 or later; the latest version at our last check was 2.1.222). In fullscreen mode, /context collapses the per-item breakdown to keep the grid visible; pass all (i.e. /context all) to expand it.

OfficialMeet two neighboring commands while you are here: when the conversation gets long, /compact compresses it into a summary to free space, while /clear simply starts a new conversation with a blank context. Also, MCP tools' full definitions are lazy-loaded by default — until a tool is used, only its name occupies context — and /mcp shows each server's token cost. No need to dig deeper today; just know that every number you see in /context has a traceable source.

Hands-on: doable today

This assumes Claude Code is installed and you are logged in. About 30 minutes total, and none of your files will be modified.

1. Go to a project directory you know well and run claude. Expected: the interactive UI opens with an input box.
2. Immediately type /context. Expected: a colored grid plus an itemized list; at this point usage is mostly the "loaded at start" parts — system prompt, system tools — with conversation messages near zero. Note the rough numbers: this is your baseline.
3. Send your first task and watch the "gather context" phase:

   Summarize what this project does in three sentences, and list the files you actually read to answer this.

   Expected: you can watch Claude call search and read tools, picking only a handful of files to read — verifying with your own eyes that it does not read the whole repo up front.
4. Now run one full loop (gather → act → verify, all visible):

   Pick the simplest automatically verifiable check in this repo (a test suite or lint, say),
   run it once and tell me the result. If it fails, only explain why - do not modify any files.

   Expected: Claude first finds the check command (gather), asks for your confirmation before executing (act; why it asks is D3's topic), then reads the output and reports back (verify).
5. Try interrupting and steering. While it is executing, type "by the way, tell me what you plan to do next" and hit Enter. Expected: once the current action finishes it reads your message and adjusts its response; to stop it immediately, press Esc.
6. Type /context again and compare with step 2. Expected: the conversation-message portion is visibly bigger, and the growth comes mostly from tool results (files read, command output). You just watched the desk fill up.

How to know you've learned it

• You can name the three phases of the agentic loop without notes, and explain why they "interleave" rather than form a fixed pipeline (hint: every tool result changes the next step).
• You can list at least 5 kinds of content in the context window, and name two things that do not enter it automatically.
• You ran /context twice during the hands-on and can explain which layer accounts for the difference between the two readings.
• Self-test: in a brand-new session, does Claude remember the conventions you agreed on last session? Why? Where should you put them so it remembers every time? (Answer: no — sessions are independent and each new session starts from a blank context; put them in CLAUDE.md, covered in D4.)