Claude Code Context Window Mastery — 7 Production Patterns to Stop Sessions From Stalling

Pattern 2: Measure token usage in real time

Intuition leads you to fix the wrong thing. Without measurement, you will swear that "MCP servers are eating my context" when actually it is a single oversized file read happening on every other turn. I run the script below in a separate terminal during sessions; it polls the latest file under ~/.claude/sessions/ every five seconds and shows the cumulative token usage with color-coded warnings.

#!/usr/bin/env bash
# claude-context-watch.sh — live token meter for the active session
set -euo pipefail
 
SESSION_DIR="${HOME}/.claude/sessions"
THRESHOLD_WARN="${THRESHOLD_WARN:-120000}"
THRESHOLD_DANGER="${THRESHOLD_DANGER:-160000}"
 
while true; do
  latest=$(ls -t "${SESSION_DIR}"/*.jsonl 2>/dev/null | head -1)
  if [[ -z "${latest}" ]]; then
    echo "$(date +%H:%M:%S) no session file found" >&2
    sleep 5
    continue
  fi
 
  read -r in_tok out_tok < <(
    tac "${latest}" \
      | grep -m1 '"usage"' \
      | python3 -c '
import json, sys
line = sys.stdin.read()
try:
    data = json.loads(line)
    usage = data.get("usage", {})
    print(usage.get("input_tokens", 0), usage.get("output_tokens", 0))
except Exception:
    print(0, 0)
'
  )
 
  total=$(( in_tok + out_tok ))
  ts=$(date +%H:%M:%S)
  if (( total >= THRESHOLD_DANGER )); then
    printf "\033[31m[%s] DANGER %d tok (in=%d out=%d) — run /compact\033[0m\n" \
      "${ts}" "${total}" "${in_tok}" "${out_tok}"
  elif (( total >= THRESHOLD_WARN )); then
    printf "\033[33m[%s] WARN  %d tok (in=%d out=%d)\033[0m\n" \
      "${ts}" "${total}" "${in_tok}" "${out_tok}"
  else
    printf "[%s] OK    %d tok (in=%d out=%d)\n" \
      "${ts}" "${total}" "${in_tok}" "${out_tok}"
  fi
  sleep 5
done

The script handles the common failure modes — missing session file, malformed JSON line, transient read errors — and falls back gracefully so it never crashes mid-session. If tac is not installed (some macOS environments), substitute tail -r. Once this is running, you stop being surprised by sudden 180K spikes. Pick thresholds that suit your project. Mine are 120K (warn) and 160K (danger). When the meter hits danger, I run /compact immediately, no exceptions.

The important part is deciding when to compact yourself rather than letting the runtime auto-fire. Auto-compaction triggered mid-reasoning can shred the parts of context you actually need — for example, a half-completed tool plan or an in-flight design discussion. With a visible meter, you can choose a clean task boundary and compact intentionally, preserving the structure of your reasoning rather than letting it be summarized opaquely.

A second-order benefit: once you have numbers, you can attribute spikes. "After I pasted that JSON response, we jumped 18K tokens" becomes a teachable moment, not a vague feeling. Over a few weeks, you will refine your sense of what costs what.

Pattern 3: Hand-write a summary before you /compact

Left to its own devices, /compact summarizes conversation history with its own judgment. It is generally good — but in development, "what we are about to do next" tends to slip through the cracks. The compactor optimizes for compressing what was said, not for preserving what is about to happen. Right before I fire /compact, I post a structured summary myself.

State of play:
- Done: stripe webhook signature verification, 3 idempotency tests
- Pending: dispute event handler, retry logic
- Decisions: idempotency key = event.id (no transformation)
- Files touched: src/payments/webhook.ts, src/payments/idempotency.ts
 
Next action: scaffold dispute handler, then add unit tests

Because that summary lives inside the conversation as a recent message, it survives the compaction with high fidelity. The compactor preserves the most recent turns essentially verbatim, so you are effectively pinning the parts of context you care about. From my experience, this single habit makes post-compaction productivity about 30 percent better — measured by the number of follow-up clarifying questions Claude asks after compaction (fewer questions equals smoother resumption).

A second tip: include any decision rationales in the summary, not just the decisions themselves. "Adopted event.id as idempotency key" is a decision; "Adopted event.id because retries arrive with the same id, no transformation needed" is the rationale. The rationale prevents the post-compaction agent from quietly re-litigating the choice.

For deeper coverage of long-session continuity, the Claude Code Long-Session Context Integrity guide covers complementary techniques.

Pattern 4: Isolate file reads with sub-agents

Claude Code's custom sub-agent feature lets you isolate a task into its own context window. This is one of the highest-impact patterns available and it is severely underused — most teams I have talked to are aware of sub-agents but do not have any concrete ones in their ~/.claude/agents/ directory.

For example, define a sub-agent for test execution and log triage at ~/.claude/agents/test-runner.md:

---
name: test-runner
description: Runs unit tests and triages logs only. Never edits code.
allowed-tools: Bash, Read, Grep
---
 
You are a test runner. Follow these rules strictly.
 
1. Execute only the commands the user passes you.
2. For failures, report only: failed test name, one-line error summary, line number.
3. Never propose code changes (that is the main agent's job).
4. Cap each reply at 200 characters.

When the main agent calls @test-runner run npm test and summarize, the giant text block of test output never enters the main context. Only a tight summary comes back. In my measurements, the main context lasts roughly 10x longer with this in place — a session that previously hit 160K in 45 minutes now hits the same threshold in seven or eight hours of equivalent work.

The watch-out here is least-privilege tooling. If you do not constrain allowed-tools, a sub-agent will quietly start writing code, fetch documentation, and spawn its own helpers — undoing the isolation. The 200-character reply cap is also load-bearing: without it, sub-agents tend to over-report, defeating the purpose. Treat sub-agents like microservices, not like junior engineers; give them a single responsibility and a strict interface.

Other useful sub-agent specializations: a log-grepper that takes a regex and a path and returns matching lines only; a dependency-resolver that reads package.json plus node_modules/.package-lock.json and reports version constraints; a git-historian that runs git log --follow against a path and returns the last N relevant commits. Each one keeps a category of bulky text out of the main loop.

For more on sub-agent design, see the Claude Code Subagent Orchestration Mastery.

Pattern 5: Treat MCP servers as opt-in, not always-on

MCP is wonderful. It also costs you tokens whether you use it or not, because each connected server contributes its description to the system prompt. With five MCP servers always on, my own measurements showed the initial context starting roughly 12K tokens heavier — before the user types anything. That is not a rounding error.

Selective MCP loading is configured in ~/.claude/mcp.json. The pragmatic rule I follow is to enable only what this week's main task needs, with the rest disabled. The categorization that has worked well for me:

• Always on: filesystem, git
• Research weeks only: web search, browser automation
• Data-heavy weeks only: database connectors, Notion, Slack
• Rare/experimental: image generation, third-party APIs you are evaluating

I review and update the MCP enabled flags every Monday morning while planning the week. It feels small, but 12K tokens out of 200K is six percent on every single turn — and that compounds across hundreds of turns per week into a meaningful slice of your effective context budget. If you are on a paid plan, it also shows up directly on the bill.

A practical tip: keep two profiles — mcp.dev.json and mcp.research.json — and swap by symlink. This sidesteps the temptation to "just leave them all on" because changing modes becomes a single-line operation rather than a multi-flag edit.

Pattern 6: Read files in slices, not in full

The Read tool accepts line ranges. Most of us reflexively read the whole file anyway, which feeds context bloat. Get into the habit of explicit slicing — and, more importantly, of asking the agent to slice on your behalf.

Read src/payments/webhook.ts lines 100 to 180 only.
If you need to understand the file shape first, grep the function definitions
and decide what to load based on that.

When a single file is over 2,000 lines, full reads are almost always overkill. A useful early-session move is to dump just the "table of contents" of a file:

# Extract function/class declarations only (TypeScript example)
rg -n '^(export\s+)?(async\s+)?(function|const|class)\s+\w+' \
   src/payments/webhook.ts \
   --max-columns 200

Paste that into chat with "based on this, suggest which functions are worth loading," and Claude will narrow the read range autonomously. The principle is simple: give it enough information to decide what to look at, before it goes looking. This inverts the default flow, in which the agent decides to look at everything and only narrows down after the fact.

For polyglot codebases, here is the same pattern adapted to a few common languages — keep these as snippets in your shell history:

# Python
rg -n '^(class|def|async def)\s+\w+' app/main.py --max-columns 200
 
# Go
rg -n '^(func|type|var|const)\s+\w+' internal/payments/webhook.go
 
# Rust
rg -n '^(pub\s+)?(fn|struct|enum|trait|impl)\s+\w+' src/lib.rs

A complementary trick: use rg --files | rg payment to enumerate file paths matching a keyword without reading any of them. Path lists are nearly free in token cost compared to file contents.

Pattern 7: Run sessions short and dense

The last pattern is operational rather than technical. Make each session deliberately small, and start a fresh one when you are done. This single shift outperformed every other technique in my own workflow.

The current rules I follow:

• One session = until one PR is ready
• Maximum session length = 90 minutes
• On exit, always save a session summary to docs/sessions/YYYY-MM-DD-HHMM.md

The summary template I use:

# Session: 2026-04-27 10:30 — Stripe Webhook Idempotency
 
## Achieved
- 3 idempotency tests green
- Adopted event.id as idempotency key
 
## Outstanding
- Dispute handler implementation
 
## Opening prompt for next session
"Implement the stripe webhook dispute handler in src/payments/dispute.ts.
Reuse the existing idempotency.ts. Add tests in tests/payments/dispute.test.ts."

With these summaries on disk, the next session opens with "read this summary and proceed" — the smallest possible context, full speed restored. Stitching together short sessions costs less in total than stretching long ones, both in dollars and in cognitive overhead. There is also a less measurable benefit: the act of writing the summary forces you to decide what was actually accomplished, which catches scope creep before it leaks into tomorrow.

For teams, commit the docs/sessions/ directory to the repo. Anyone reviewing a PR can read the corresponding session summary to understand the agent's reasoning — a kind of structured commit message at the conversation level.

Common mistakes and how to avoid them

Three failure patterns I have watched repeat across teams.

Mistake 1: "Open all the related files for me, please"

This is the worst opener. Claude Code will infer relations from directory structure and Read files you do not actually need. Twenty files at ~300 lines each is roughly 6,000 lines, ~30K tokens, gone in seconds. Replace it with: "From this PR's diff, identify the three files that need modification first." Force candidate narrowing before file loading. A one-line git diff --name-only main...HEAD gives the agent a perfectly bounded starting set without any file contents at all.

Mistake 2: Reaching for /compact instead of /clear

/clear wipes the conversation; /compact summarizes it. When switching tasks, /clear gives you a clean window — but psychologically we want to "preserve lessons learned," so we pick /compact. The drag of carrying half-relevant history across task boundaries is a major source of context pressure on long days. When the task truly changes, choose /clear deliberately. If there are genuinely lessons to preserve, write them into a project notes file (e.g., docs/notes/agent-lessons.md) and reference it explicitly when needed, rather than carrying it implicitly in conversation.

Mistake 3: Pasting large outputs raw

Log files, SQL result sets, JSON payloads. Pasted whole, they consume 5,000-20,000 tokens instantly. Filter first: head -100, tail -100, jq '.[] | select(.status=="error")'. Most auto-compaction misfires I have seen trace back to a giant paste. A useful rule of thumb: anything over 200 lines should be summarized or filtered before it enters the conversation. The Claude Code /clear vs /compact guide goes deeper on what triggers unwanted compaction.

If you absolutely need the agent to see a large blob — for example, a stack trace from production — save it to a file first and have the agent Read it with explicit line ranges. That at least gives you control over which parts enter context.

A weekly context audit routine

Whether you work solo or on a team, a 15-minute Monday-morning audit pays back many hours later in the week. The checklist I run:

• Review the top three longest sessions of last week and identify where bloat happened
• Disable MCP servers no longer needed for this week's work
• Update the off-limits list in your scope template based on what you learned
• Confirm your session summary template still captures everything you need
• Archive old session logs from ~/.claude/sessions/ (I move anything older than two weeks to ~/.claude/sessions/archive/)

Hold this for a month and average session length will drop measurably, with response time following. For teams, sharing a common summary format means another developer can pick up your work with minimal handoff cost — which is a quiet but compounding productivity win.

If you are folding Claude Code into a production workflow more broadly, my Claude Code Failure-First Workflow Patterns pairs nicely with this article. The two together cover both the in-session and across-session axes of running Claude Code reliably.

Bonus: diagnosing why a session feels slow

Even with the seven patterns in place, you will occasionally hit a session that feels off — slower than usual, or producing patches that are subtly wrong. Before you blame the model, run through this short diagnostic in order. It takes about three minutes and resolves most "feels slow" complaints I have investigated.

Step 1: Check the meter. If you are running pattern 2, glance at the current token total. Above 140K, slowdown is expected and the fix is /compact or /clear. Below 80K, the cause is elsewhere.

Step 2: Inspect the most recent tool calls. In ~/.claude/sessions/<latest>.jsonl, look at the last 10 tool invocations. If you see repeated Read calls against the same file, the agent is re-reading because it lost track of file contents — usually a sign that compaction happened recently or that a sub-agent returned vague output. Re-paste the relevant section explicitly.

Step 3: Check MCP server health. A slow or hanging MCP server can stall the entire turn waiting on a response that never comes. The Claude Code logs at ~/.claude/logs/mcp-*.log will show timeouts. If you see them, disable the offending server temporarily and continue.

Step 4: Check your network. Sounds obvious, but a flaky connection produces what feels like model slowness. mtr api.anthropic.com will tell you in seconds whether the latency is yours or theirs.

Step 5: If all else fails, start a fresh session. Sometimes a session accumulates state in ways that are hard to see, and the cheapest fix is to write a summary, save it, and start over. This is also why pattern 7 matters — making fresh sessions a habit means this fallback feels natural rather than punitive.

Optional: build a token cost report per session

For teams running Claude Code at scale, it is worth aggregating token consumption across sessions to spot expensive patterns. The following Python script walks ~/.claude/sessions/, sums input and output tokens per session, and prints a sorted summary:

#!/usr/bin/env python3
"""claude-session-report.py — summarize token usage per session"""
from pathlib import Path
import json
import sys
 
SESSION_DIR = Path.home() / ".claude" / "sessions"
 
def session_totals(path: Path) -> tuple[int, int]:
    in_total = out_total = 0
    try:
        with path.open() as f:
            for line in f:
                try:
                    data = json.loads(line)
                except json.JSONDecodeError:
                    continue
                usage = data.get("usage", {})
                in_total += usage.get("input_tokens", 0)
                out_total += usage.get("output_tokens", 0)
    except OSError as e:
        print(f"warn: could not read {path}: {e}", file=sys.stderr)
    return in_total, out_total
 
def main() -> None:
    rows = []
    for jsonl in SESSION_DIR.glob("*.jsonl"):
        in_t, out_t = session_totals(jsonl)
        rows.append((jsonl.stem, in_t, out_t, in_t + out_t))
    rows.sort(key=lambda r: r[3], reverse=True)
    print(f"{session:<40} {input:>10} {output:>10} {total:>10}")
    for name, in_t, out_t, total in rows[:20]:
        print(f"{name:<40} {in_t:>10} {out_t:>10} {total:>10}")
 
if __name__ == "__main__":
    main()

Run it weekly as part of the audit routine and you will quickly spot which kinds of work generate the most tokens — usually large refactors and "explore an unfamiliar codebase" sessions. Knowing this lets you proactively split those workloads into smaller sessions before they become expensive.

The script handles malformed lines and missing files gracefully, so you can run it against a live session directory without worrying about race conditions. Output is intentionally simple — pipe it into column -t or import into a spreadsheet if you want prettier formatting.

Where to start this week

You do not need to adopt all seven patterns at once. The single highest-leverage move you can make today is running pattern 2's measurement script. Once you can see token usage in real time, you will instinctively know what to fix next — whether it is sub-agent isolation, MCP pruning, or simply slicing your reads.

As an indie developer maintaining the Dolice Labs sites and apps single-handedly, I watch these numbers closely. To put numbers on what this whole framework changes: in the three months since I formalized these patterns, my average session length dropped from 73 minutes to 38 minutes, and my average per-session token consumption fell from 145K to 71K. The PR throughput per week stayed flat — I am not doing less work, I am just spending less context to do it. The compounding effect is that long-running multi-week projects are now genuinely sustainable on Claude Code, where previously they would degrade into "babysit the agent and hope" by week three.

If you are leading a team, my suggestion is to introduce these patterns one at a time over a sprint, with a brief retrospective on each. Pattern 1 (scope template) and pattern 2 (measurement script) have the fastest payoff and are the easiest to evangelize. Patterns 4, 5, and 7 require small tooling changes per developer but pay off most heavily in long-term consistency. Skip nothing — every pattern I included survived a "would I really notice if I dropped this?" test.

This site runs on a single-developer budget — server costs and validation API bills are covered by reader support, and there are no ads. If this article saved you a frustrating debugging session, the tip jar or membership at the bottom of the page is what keeps the next round of testing happening. Thank you for reading to the end.