Inside one Claude Code session

TL;DR. A Claude Code session is one long, growing context that the tool rebuilds and re-sends on every turn. It is assembled in a fixed order: the system prompt, the tool definitions, then your CLAUDE.md and auto-memory index delivered as a user message, then the conversation and tool results. The stable front of that sequence is cached, so you pay full price for it once and about a tenth after; the new tail is what each turn really costs. /context shows you the live breakdown and /usage shows the tokens and dollars. Master those two views and the rest of context engineering in Claude Code is just moving things between the cached front and the expensive tail.

Contents

What is actually in the context at turn zero
How the request is segmented for the cache
How the context grows, turn by turn
Reading the two gauges: /context and /usage
Where MCP and tools fit
Further reading
Takeaways

Everything earlier in this book was mechanism: how compression, caching, memory, and orchestration work, each built from scratch. This chapter and the two after it are the mechanism made concrete in one tool, Claude Code, Anthropic's command-line coding agent. The reason to study it closely is that it is an honest, production example of every lever at once, and it exposes the internals through commands you can run, so you can see the context instead of reasoning about it in the abstract. This chapter is the anatomy of a single session. The next is how state survives across sessions and projects. The one after is the full command and configuration surface, with the strategies that separate a casual user from a specialist.

What is actually in the context at turn zero

Before you type anything, a Claude Code session already has a populated context window. It is not empty and it is not free. Here is what is in it, in the order it is assembled, because the order is what makes caching work later.

   ┌───────────────────────────────────────────────────────────┐
   │ 1. SYSTEM PROMPT                                            │  the agent's
   │    Claude Code's own instructions: how to use its tools,    │  identity and
   │    how to edit files, its safety and style rules.           │  rules
   ├───────────────────────────────────────────────────────────┤
   │ 2. TOOL DEFINITIONS                                         │  the verbs
   │    JSON schemas for Read, Edit, Bash, Grep, Task, etc.,     │  the agent
   │    plus any MCP tools that are loaded (see below).          │  can use
   ├───────────────────────────────────────────────────────────┤
   │ 3. CLAUDE.md (+ rules + MEMORY.md index)  ── a USER message │  YOUR
   │    Your project and user instructions, your path-scoped     │  persistent
   │    rules, and the first 200 lines of auto-memory's          │  context
   │    MEMORY.md. Delivered AFTER the system prompt, as the     │
   │    first user turn, not as part of the system prompt.       │
   ├───────────────────────────────────────────────────────────┤
   │ 4. CONVERSATION                                             │  the live
   │    Your messages, Claude's replies, and every tool result   │  work, grows
   │    (file contents, command output) appended in order.       │  every turn
   └───────────────────────────────────────────────────────────┘

Three of these four are fixed the moment the session starts. The system prompt and the tool definitions come from Claude Code itself. Your CLAUDE.md and the auto-memory index come from disk. Only the fourth, the conversation, is empty at turn zero and grows from there.

One internal detail matters more than any other, and most people get it wrong. CLAUDE.md is not part of the system prompt. It is delivered as a user message, right after the system prompt, at the start of the conversation. The official memory documentation says this plainly, and it explains a behavior people find surprising: instructions in CLAUDE.md are guidance Claude reads and tries to follow, not configuration the client enforces. If you need a rule enforced no matter what the model decides, that is a job for a hook or a permission setting (Chapter 19), not a line in CLAUDE.md. If you need a rule injected at the true system-prompt level, that is --append-system-prompt, which you pass on every invocation.

Don't be confused. The system prompt is Claude Code's own operating manual, written by Anthropic, and you only append to it with a flag. CLAUDE.md is your content, delivered as the first user message. They sit next to each other in the context but they are different channels with different authority: the system prompt shapes the agent, CLAUDE.md advises it. This is why "it ignored my CLAUDE.md" happens and "it ignored its system prompt" effectively does not.

How the request is segmented for the cache

That assembly order is not arbitrary. It is exactly the order that makes prompt caching (Chapter 6) pay off. Caching is a prefix match: the provider reuses its stored computation for the longest run of tokens that is byte-identical to a previous request. So Claude Code puts the things that do not change from turn to turn at the front, and the things that change at the back.

   <-------------------- STABLE PREFIX (cached) -------------------->  <-- VOLATILE TAIL -->
   [ system prompt ][ tool definitions ][ CLAUDE.md + MEMORY.md ]      [ conversation so far,
                                                                         your new message,
                                                                         new tool results ]
   paid in full on turn 1, then re-read at ~0.1x on every later turn    paid in full every turn

On the first turn, the whole stable prefix is a cache write: Claude Code processes the system prompt, the tools, and your CLAUDE.md, and the provider stores the result. On every later turn in the session, that same prefix is a cache read at roughly a tenth of the input price, because it has not changed by a single byte. The only tokens you pay full input price for after turn one are the genuinely new ones: your latest message and any file or command output it pulled in.

This is the mechanical reason for the most repeated advice about CLAUDE.md: keep it small and keep it stable. Small, because it sits in the prefix and is re-read on every single turn, so a 5,000-token CLAUDE.md is a 5,000-token baseline you carry all session even when it is mostly cached. Stable, because editing it mid-session changes the prefix, which invalidates the cache from the edit point onward, so the next turn pays a full write again to rebuild it. The win from caching is real but fragile: one moving byte near the front forfeits the discount behind it.

Remember. The front of the context is cheap and the back is expensive. Everything you can push into the stable, cached prefix (and keep stable) is paid for once; everything in the volatile tail is paid for every turn. Context engineering in Claude Code is largely the art of keeping the right things at the front and the noise out of the back.

How the context grows, turn by turn

The session starts at its baseline (system prompt plus tools plus your instructions) and grows with every turn. The thing to internalize is what grows, because it is rarely your prose. It is the tool results.

Walk a normal turn. You ask Claude to fix a bug. It reads three files (each file's full text lands in the context), greps the tree (the matches land in the context), runs the tests (the test log lands in the context), then writes its reply. Your message was maybe 20 tokens. The file reads, the grep output, and the test log were thousands. By the next turn, all of that is behind you in the conversation, and it is all re-sent, because the model is stateless and the whole conversation is the context (Chapter 1).

This is the single most important fact about session cost, and it is why the later chapters lean so hard on three moves:

Read less (Chapter 5): Claude Code greps and reads targeted lines, not whole files, so the tool results that land in the context are small.
Delegate verbose work (Chapter 13): a subagent runs the tests in its own context window and returns one line, so the 3,000-token log never enters your session at all.
Compact when it fills (Chapter 11): when the window approaches its limit, old turns are summarized so the session can continue.

A useful intuition: your typed words are a rounding error in a coding session. The budget is spent on what the tools pull in. Manage the tool output and you manage the session.

Reading the two gauges: /context and /usage

Claude Code exposes the context directly through two commands. A specialist watches both.

/context prints a live breakdown of what is filling the window right now, by category, with the share each takes. It is the input-side gauge: it answers "what is in my context and what is dominating it." A reading mid-session looks like this (the layout is representative):

> /context
  System prompt + built-in tools .....  14k   (7%)
  MCP tools .........................   6k   (3%)
  CLAUDE.md + rules + memory ........   4k   (2%)
  Files read (11) ...................  78k  (39%)
  Tool results (tests, grep, logs) ..  61k  (30%)
  Conversation ......................  18k   (9%)
  Free ..............................  19k  (10%)

Read that and the lesson jumps out: the system prompt, tools, and your instructions are a small, fixed base (here about 12%). The window is dominated by files read and tool results, which is exactly where the levers apply. When Claude starts to feel forgetful, or before you tune anything, /context is the first place to look.

/usage (older versions exposed the session figure as /cost) is the spend-side gauge. It reports the session's token counts and an estimated dollar figure, and on a subscription plan it attributes recent usage to skills, subagents, plugins, and individual MCP servers. It answers "where did the money go," which is often a different question from "what is in the window," since the expensive output tokens (Chapter 2) do not sit in the window at all.

Don't be confused. /context measures the input side, the tokens currently occupying the window. /usage measures spend, including the output tokens the model generated, which are billed at about five times input and then mostly leave the window. Watch /context when the window is filling; watch /usage when the bill is climbing. They are different instruments for different problems.

Where MCP and tools fit

The tool definitions in slot 2 deserve a closer look, because they are a common, invisible source of bloat. Every tool the agent can call has a JSON schema (its name, description, and parameters) that lives in the context so the model knows the tool exists. Built-in tools (Read, Edit, Bash, Grep, Task) are compact. MCP servers (Model Context Protocol servers, external programs that expose extra tools) can add many tools, and their definitions add up.

Claude Code handles this with tool-search deferral: by default, MCP tool definitions are not all loaded into the context. Only the tool names are present until the model actually reaches for a specific tool, at which point its full schema is fetched. This keeps a dozen connected MCP servers from each spending hundreds of tokens of always-present schema. You can see what tools and servers are costing you with /context and manage them with /mcp. The official cost guidance is blunt about the trade: a plain CLI tool such as gh or aws, which the agent just runs through Bash, costs nothing in per-tool listing, so it is often more context-efficient than the equivalent MCP server.

This is the same theme as the rest of the chapter. Everything that sits in the context, even the list of tools, is paid for. The job is to keep the always-present part small and let the rest load on demand.

Takeaways

A Claude Code session is one growing context, reassembled and re-sent every turn, in a fixed order: system prompt, tool definitions, CLAUDE.md and memory index (as a user message), then the conversation.
CLAUDE.md is delivered as a user message after the system prompt, so it is guidance, not enforcement. Use a hook or a setting to enforce; use --append-system-prompt for system-level text.
The stable prefix (system, tools, instructions) is cached: paid in full once, re-read at about 0.1x after. Keep CLAUDE.md small and stable so the cache holds.
The window is dominated by tool results, not your prose. Reading less, delegating verbose work to subagents, and compacting are the three moves that control session cost.
/context is the input-side gauge (what is in the window); /usage is the spend-side gauge (where the money, including output tokens, went). A specialist watches both.

👉 A single session is bounded by the window. The next chapter is how knowledge escapes that boundary: how memory persists across turns, across sessions, and across whole projects, through the CLAUDE.md hierarchy and auto memory. Continue to Memory across sessions and projects.

Context Engineering in Depth