Sessions & Context Windows

Tier 1 · Fundamentals 7 min read

Every Claude Code session has a context window — a fixed amount of text the model can hold in its working memory at once. When that window fills, the session either fails in confusing ways or gets rotated. Understanding how this works is not advanced knowledge; it’s the first thing that trips up new users, and it shapes almost every design decision in a larger agent system.

What a session is

When you run claude in your terminal, you start a session — a running conversation between you and the agent, plus all the tool calls, results, file reads, and edits the agent makes along the way. All of that goes into the context window.

The context window is finite. Current Claude models support 1 million tokens (roughly 750,000 words of plain text — the equivalent of several long novels). That sounds enormous until you realize that every file the agent reads, every command output it sees, every round of thinking it does, and every exchange between you all count against that budget. A long coding session with many file reads can fill a million-token window.

What happens when the window fills

The model doesn’t fail gracefully when it runs out of context. Depending on how you’re using it, you might see:

Truncation — early parts of the conversation drop off silently, and the agent loses context about what it already did.
Compaction — some harnesses automatically summarize old context to make room; Claude Code does this when it detects the window approaching its limit.
Errors or hallucinations — the agent tries to reference something it can no longer see, gives stale or invented answers, or simply gets confused.

None of these are what you want in the middle of important work.

Session rotation

A session rotation is a deliberate restart. When the window approaches its limit, the agent finishes what it’s currently doing, writes any important state to files, and starts a fresh session.

The key word is “writes to files.” Because state lives on disk, not in conversation memory, a rotated session can pick right back up:

The new session reads the CLAUDE.md instructions.
It reads the project WORKPLAN.md and CHANGELOG.md to know what’s in flight.
It reads whatever state files the previous session was working from.
It continues the task as if no gap occurred.

This is why “files as state” (the next article) is the single most important doctrine in the system. Without it, rotation means losing everything. With it, rotation is a routine maintenance step, no different from saving your work.

When to start fresh

Beyond automatic rotation, there are situations where you should deliberately start a new session:

Task is done. Don’t keep one mega-session running forever. When you finish a task, end the session so the next one starts clean.
The agent is confused. If it keeps circling, contradicting itself, or referencing something from earlier in the conversation that it’s gotten wrong, a fresh session often resolves it faster than extended troubleshooting.
Switching to an unrelated task. Context from one problem bleeds into another. The cost of a fresh start is low; the cost of contaminated context is high.
Something destructive was about to happen. You can abort a session at any time with Ctrl-C. The files on disk are unchanged unless the agent already wrote them.

A practical heuristic

A good rule: treat sessions like browser tabs, not like long-lived processes. Open one for a task, work the task to completion, close it. If the task will take hours and many file reads, expect to rotate once or twice — that’s normal, not a problem.

In a larger agent system where sessions run on a schedule (Tier 2 territory), rotation is handled automatically. The agents write their state to yaml files and CHANGELOG.md before the session ends, and the next run re-reads them. The system’s memory is in the files, not the chat.

Next: Files as State, Not Chat Memory — the doctrine that makes session rotation painless and agent memory persistent.