Skip to content

5.5 Managing Long Sessions

Every builder eventually notices it: the session that started brilliant turns mushy around hour two. Suggestions get generic, earlier instructions get forgotten, the agent re-litigates settled questions. That's not the model getting tired — it's the context window getting crowded. This lesson teaches session shape: when to clear, how compaction works, and how to split work so quality never sags.

What you will learn

  • Diagnose context crowding from its symptoms.
  • Use /clear, compaction, and the second brain as one continuity system.
  • Shape work into right-sized sessions instead of marathon mega-chats.

Builder principle

Sessions are sprints, not shifts. End them on purpose, bank the knowledge, start the next one clean.

Why long sessions decay

Three compounding effects, all downstream of Lesson 2.2:

  1. Crowding. The window fills with every file read, every command output, every dead end. Signal-to-noise falls; the model weights what's prominent, and by hour two, noise is prominent.
  2. Compaction loss. When the window nears capacity, Claude Code compacts — summarizes older conversation to reclaim space. Summaries preserve the gist and shed detail. Which detail? You don't control that — and sometimes it was the detail that mattered.
  3. Contradiction buildup. You changed direction twice; all three directions still live in context. The agent is now honoring instructions you've mentally revoked but textually haven't.

The symptoms, so you catch it live: forgetting recent instructions · generic "best practices" answers replacing project-specific ones · re-proposing things you rejected an hour ago · sluggish, rambling responses. Any two of these = the whiteboard is full.

The countermove: clear + banked knowledge

Beginners fear /clear — "I'll lose everything we built up!" But you've spent three lessons making that fear obsolete:

CLAUDE.md + the second brain = everything worth keeping, already outside the window. /clear deletes the scaffolding, not the building.

The professional end-of-task rhythm:

1. Task done, verified, committed.
2. Librarian prompt: update docs/log.md (and decisions.md if warranted).
3. /clear
4. Next task starts with a clean window + CLAUDE.md + fresh log entry.

A cleared session that reads a good log entry is sharper than hour-three of a mega-session — it has all the signal and none of the sediment. Once you've felt that difference, /clear stops feeling like loss and starts feeling like opening a window in a stuffy room.

Right-sizing sessions

The deeper skill is shaping work so sessions end at natural banking points:

One session = one outcome. Not "work on the site" — that's a shift. "Ship the testimonials section" — that's a sprint with a finish line, a verification, a commit, and a clean exit.

Split big outcomes at the seams. A feature too big for one session splits where the work banks naturally: plan session (plan mode, decisions into decisions.md) → /clear → build session (execute against the written plan) → /clear → polish session. Each starts clean, reading the banked artifacts of the last. This is the same five-station Builder Loop (4.5), just run at session granularity.

Compaction awareness, not compaction fear. Auto-compaction is a decent safety net — but "the agent got summarized mid-task" is a state you'd rather not need. If you see the window filling (long transcript, many files read) near a natural checkpoint: bank and clear on your terms instead.

Simple heuristic that never fails: when you'd take a coffee break, the session takes one too. Verify → commit → librarian prompt → /clear → break. You return fresh; so does it.

Extra lever: separate broad exploration from focused building. Large investigations can add low-relevance context. A separate session or scoped subagent (Chapter 10) can return evidence and conclusions while the build session keeps the plan and relevant files in view. Test whether that separation improves your task rather than assigning it a universal productivity percentage.

Try it now

  1. Recall your longest session so far. In your journal: which decay symptoms, if any, did you see? (Now you have names for them.)
  2. Take your next real piece of work and pre-shape it: write down the session boundaries before starting — outcome, banking point, clear.
  3. Run the first sprint exactly to shape: outcome → verify → commit → librarian → /clear.
  4. Note how the next session's first response feels. That crispness is what you're engineering for.

Check your understanding

  • Name the three decay mechanisms and two live symptoms of each... or any four symptoms total.
  • What exactly is lost in compaction, and who chooses what's lost?
  • Why is /clear safe in this course's workflow when it feels dangerous in a bare chat?
  • What's the one-session-one-outcome rule, and where do oversized outcomes split?