The Context Window

You have seen what Claude Code can do. This lesson is about the constraint underneath all of it, and it is the most useful thing in the course. Once you understand this, most of the advice in the remaining lessons stops being a list of tips and becomes obvious.

Everything Claude knows lives in one place

Claude has no memory between messages. Every time you press Enter, Claude Code sends the model the whole situation again: the instructions, the project context, the conversation so far, every file that was read, every command that was run and what it printed. That bundle is the context window, and it has a fixed size.

The window is measured in tokens, which are roughly chunks of a word. You do not need to think in tokens precisely. What you need is a sense of scale: a prompt is tens of tokens, a source file is a few thousand, a verbose test run can be more than that.

Three kinds of thing occupy it.

That last row is the one people underestimate. In your terminal you see Read src/api/auth.ts on one line. What entered the window was the file.

The constraint

Here is why any of this matters.

Notice what this is not. It is not that the session stops working. Claude Code compacts automatically as you approach the limit, so you rarely hit a wall. The failure mode is softer and harder to spot: the same agent that was sharp forty minutes ago starts ignoring a convention you established, or re-reads a file it already read, or fixes the bug you mentioned two hours ago instead of the one you mentioned just now.

Watching it fill

claude

1. WhyBefore this session shows a single line, roughly six or seven thousand tokens are already loaded: system instructions, both CLAUDE.md files, auto memory, and the descriptions of every skill available.

2. >You typed: Users get a 401 after their token refreshes. Have a look.

3. Claude ran: Read src/api/auth.ts

4. Claude ran: Read src/lib/tokens.ts

5. Claude ran: Read src/middleware.ts

6. WhyThree one-line entries in your terminal. Several thousand tokens in the window. Your prompt was about forty.

7. Claude ran: Search: refreshToken

8. Claude ran: Run: npm test auth

9. Output: FAIL  auth.test.ts
     expected 200, received 401
     (47 lines of stack trace)

10. WhyThe stack trace enters the window in full, not as the summary you see. Failing test output is one of the more expensive things a session accumulates, and a debugging session produces a lot of it.

11. Claude replied: The old token is invalidated before the new one is written. I'll reorder that and add a regression test.

12. Claude ran: Edit src/api/auth.ts

13. Claude ran: Run: npm test auth

14. Output: PASS  auth.test.ts  (12 tests)

Nothing here was wasteful. This is what a normal, well-run task costs. Which is the point: context fills up during ordinary good work, not only when you do something wrong.

What happens when it fills

Claude Code handles the limit for you, in two stages.

1. Step 1

   Older tool output goes first

   The full text of files read and commands run earlier is cleared out, because it is bulky and usually no longer needed.

2. Step 2

   Then the conversation is summarised

   If that is not enough, the message history is replaced by a structured summary: your requests, the key code, the errors and how they were fixed, and what is still outstanding.

3. Step 3

   Work continues

   Claude keeps going from the summary. Most of what loaded at startup is reloaded from disk, so CLAUDE.md and auto memory come back intact.

Compaction is genuinely useful — it is what lets a long session continue at all. But read the second step again, because it has a consequence people meet the hard way.

Detailed instructions from early in the conversation can be lost. The summary keeps your intent and the important code. It does not reliably keep the sentence you typed ninety minutes ago about never touching the legacy/ directory.

This is the reason a rule you care about does not belong in the chat. It belongs in CLAUDE.md, the file Claude Code reads at the start of every session, because that file is re-injected from disk after compaction rather than summarised away. There is a whole lesson on writing one later. For now, the instinct is enough: if it must hold for the whole session, it goes in a file, not in a message.

One caveat worth knowing now. Your project and user CLAUDE.md are read once when the session starts and held from then on. Editing one mid-session does not take effect until the next /clear, /compact or restart.

Look at your own

You do not have to guess at any of this. Run /context and Claude Code prints a live breakdown of what is currently occupying the window, by category, along with suggestions. It will tell you which CLAUDE.md and memory files loaded, and if you use MCP servers, /mcp shows what each one costs.

Run it once in a session that feels sluggish and once in a fresh one. The comparison teaches more than any explanation.

Four ways to spend less

Clear between unrelated tasks. /clear starts a fresh conversation. When you finish one job and start another that shares nothing with it, the old conversation is pure cost — it crowds out the files you need next and you pay for it on every message.

Compact deliberately, with a focus. Rather than waiting for the automatic pass to guess what matters, run /compact at a natural break, and tell it what to keep: /compact focus on the API changes. You choose what survives.

Let skills stay unloaded. Skills are reusable instructions you can add to a project. Claude sees only a one-line description of each at startup; the full content loads only when a skill is actually used. That design is deliberate, and it is why a large library of skills does not weigh a session down.

Delegate reading to a subagent. A subagent is a second Claude that runs with its own separate context window. It can open twenty files researching a question, and none of that touches your window — only its final summary comes back. For anything that involves a lot of reading and a small answer, this is the single biggest saving available.

Both skills and subagents get full lessons later. They are mentioned here because both exist primarily as answers to this one problem.

What to take away

Everything Claude knows during a session sits in one fixed-size window: the startup content, your conversation, and — dominating both — every file read and every command output. Model performance degrades as that window fills, which is a quiet failure rather than a loud one. Auto-compaction keeps the session alive by clearing old tool output and then summarising the conversation, and the casualty is usually the detailed instruction you gave early on, which is why persistent rules belong in CLAUDE.md rather than in a message. Use /context to see where you stand, /clear between unrelated work, /compact with a focus at natural breaks, and subagents for anything that requires reading a lot to learn a little.

Next: how to write a prompt that gets the right result the first time, which is partly a clarity problem and — now you know this — partly a context one.