Everything a coding agent "knows" while working on a task has to fit inside one number: its context window. This guide explains what actually fills that window during a session, why answers quietly get worse long before it overflows, and how instruction files like CLAUDE.md and AGENTS.md give an agent a memory that survives when the conversation doesn't.
A context window is the total span of tokens — input and output combined — a model can process in a single call. It is not a database and it is not memory in any durable sense; it is closer to working memory that must be resupplied, in full, every time. Model calls are stateless: nothing persists inside the model between one call and the next. Whatever an agent seems to "remember" from ten minutes into a session is only there because the harness resent the entire transcript so far as part of the new prompt.
For an agent working through the agent loop of prompt, tool call, observe, repeat, this has a blunt consequence: your original instructions, every file it opened, every command it ran and the output that came back, and the full back-and-forth conversation all have to be re-sent, in full, inside the same bounded window, on every single turn. There is no side channel and no scratchpad the model quietly consults later. If a fact is not sitting in the window at the moment the model generates its response, the model cannot act on it — no matter how clearly it was stated fifty turns earlier.
Advertised window sizes move fast and vary by vendor and model tier — treat any specific number you've heard as a snapshot, not a constant, and check your model's current documentation before relying on it. What doesn't move is the shape of the problem: whatever the number is, a long session will eventually press against it, and — as the next few sections show — things go wrong well before that ceiling is reached.
Models don't read words; they read tokens — the subword pieces a tokenizer splits text into before anything reaches the model. For ordinary English prose, a workable rule of thumb is one token ≈ ¾ of a word, or roughly four characters. A quick way to hold that in your head: about 750 words of prose costs around 1,000 tokens.
Code tokenizes denser than prose of the same length. Punctuation, indentation, operators, and identifiers written in camelCase or snake_case tend to split into more, shorter tokens than the equivalent stretch of natural-language text, because tokenizers are trained on text that skews heavily toward prose — code is a less efficient fit for the same vocabulary. The practical result: a modest 200-line source file can easily cost 1,500–3,000 tokens, more than several paragraphs of written instructions.
This matters because tokens are the currency actually being spent against the one constraint from section 1. Every file an agent reads, every command's output, every line of a build log draws from the exact same finite budget as the instructions you gave it — there is no separate, cheaper lane for "just looking something up."
Byte-pair encoding and its relatives. Most current models use a variant of byte-pair encoding (BPE) or a similar subword scheme: common character sequences get merged into single tokens during training, so frequent words often collapse to one token while rare words split into several. Exact token counts differ between model families, since each ships its own trained vocabulary.
The ¾-word ratio is English-specific. Languages with different scripts or morphology, and dense structured data like JSON or minified code, can tokenize noticeably less efficiently — the same information can cost more tokens than the character count alone suggests.
An agent session accumulates in layers, and every layer is resent on every turn:
CLAUDE.md, AGENTS.md, skill files, whatever the harness auto-loads before the first turn.Layer four is usually the one that dominates. A single failing test run, a repo-wide search, or a verbose build log can be several thousand tokens on its own — often far larger than the actual instruction that triggered it. The signal an agent needs to act on is frequently a small fraction of the volume a tool call returns, and all of that volume still has to sit in the window regardless of how much of it turns out to matter.
Try toggling the mode after you've advanced through a few layers: switching between a couple of targeted file reads and a full repository dump changes nothing about the task you're solving, but it changes almost everything about how much room — and how much attention — is left for the model to solve it with.
A model's attention across a long context is not uniform. Details and instructions measurably lose influence over the output as more tokens accumulate around them — well before the window's hard limit is reached. This is sometimes called context rot, and a related, more specific pattern is often described as "lost in the middle": models tend to make better use of information near the start or the very end of a context than information buried in the middle of a long transcript.
The mechanism, at a reasonable level of precision: transformer self-attention scores every token against every other token, but those scores come from learned patterns, not a guaranteed-perfect index. As the token count grows, a given instruction or fact has to compete with a growing volume of tool output and side conversation for the same finite attention budget. The tokens are technically still there — nothing was deleted — but empirically they get weighted less, and the model's output drifts away from honoring them.
The symptom in practice: an agent quietly stops following a constraint you gave forty turns ago, or reintroduces a bug it already fixed, long before any length-related error fires. Headroom left in the window and answer quality remaining are not the same measurement — the meter in section 3 can still show plenty of green while the model's grip on your earlier instructions has already started to slip.
An agent has 60% headroom left in its window but starts ignoring an instruction from early in the conversation. What's happening?
When a session approaches its budget, most agent harnesses trigger compaction (sometimes called summarization): the oldest portion of the transcript gets replaced with a condensed synthesis, while the system prompt, instruction files, and the most recent turns stay verbatim. Without it, a long session would simply hit the hard limit and stop working; compaction trades precision for headroom so the session can keep going.
What tends to survive: explicit decisions ("use a cache with a 10-minute TTL"), open tasks, and file paths that were touched — anything structured enough that a summarizer judges it worth a sentence. What tends to drop: exact command output, incidental facts mentioned once in passing, and exploratory steps that didn't lead anywhere. A detail that mattered but was never flagged as a decision looks, to a summarizer, exactly like a detail that didn't matter at all — the two are indistinguishable from the outside.
Conversation memory is ephemeral — it ends when the session ends, and gets thinned by compaction well before that if the session runs long. The pattern that actually holds up is treating the repository itself as the agent's long-term memory. Instruction files — CLAUDE.md, AGENTS.md, or an equivalent your harness supports — are read fresh at the very start of every session, before any conversation happens at all, which makes them the one thing that reliably survives no matter how the previous session ended.
The corollary is worth stating plainly: telling an agent something in conversation only helps for the rest of that conversation. Writing the same thing into a file the agent reads at session start helps every session from now on, including ones run by a different agent instance that never saw the original conversation. Repeating an instruction to a fresh agent costs tokens and trust every time; writing it once into a committed file costs nothing on every future run — that asymmetry is the entire argument for "write it down in the repo" over "tell the agent again."
Task-scoped notes work the same way at a smaller radius. A written spec records what's done and what's next as an artifact, not a turn in the conversation, so a fresh session — of the same agent or a different one — can resume a half-finished task without replaying the discussion that produced it. This matters most exactly when compaction has already thinned the earlier context: the spec file was never inside the conversation window to begin with, so there was nothing for compaction to drop.
None of this requires a smarter model — it requires treating the window as the scarce, shared resource it is:
git log and a diff is cheaper and more reliable than reconstructing it from a compacted summary of the conversation that produced it. See how commits and worktrees fit into a workflow with more than one agent.TermRoam doesn't change how context windows work — nothing can — but it removes the reasons sessions balloon past the point where quality has already started to slip. Persistent terminal sessions mean starting a fresh, scoped session costs nothing: no lost terminal, no re-establishing a connection, nothing to reboot, so there's no incentive to keep one long-running conversation going just to avoid the setup cost of a new one. The execute pipeline enforces one-commit-per-step by default, so "what happened" lives in git log rather than in a conversation that will eventually get compacted. And every box ships its instruction files pre-committed, so a new agent's very first read is already the durable memory this guide describes.