Stop Losing Context: How Auto Handoff Works

Update, October 2026: this post describes an earlier Brewcode version, and some of the features and commands it presents are retired. See the current docs.

A regular Claude Code session has a hard limit: the context window. When your conversation fills it up, the system compacts older messages to make room. Compaction is lossy — details, decisions, and discovered patterns disappear. If you are midway through a multi-file refactor, compaction can derail the entire task.

Auto Handoff solves this by saving knowledge before compaction happens and restoring it when the next session starts.

The Problem

Here is what normally happens during a long session:

1. You start a complex task — say, migrating 40 files from one API pattern to another.
2. Claude learns your codebase conventions, discovers edge cases, and builds a mental model of the work.
3. At ~80% context capacity, the system compacts. Older messages are summarized or dropped.
4. Claude loses the detailed mental model. It re-reads files it already understood, re-discovers conventions it already learned, and sometimes contradicts decisions it made earlier.

The longer the task, the worse this gets. Multi-phase plans that span several compaction cycles can lose hours of accumulated knowledge.

How Auto Handoff Works

Auto Handoff intercepts the compaction process and adds three steps:

Save phase — at approximately 90% context capacity, before compaction triggers, the plugin scans the conversation for knowledge entries. These are facts Claude has stated about your codebase: naming conventions, architectural decisions, edge cases, file relationships. Each entry is written to a JSONL file with a timestamp and category.

Handoff state — the plugin writes a structured summary of the current task state: what has been completed, what remains, which files have been modified, and any open questions. This state document is compact — typically 200-400 tokens — but captures the essential execution context.

Resume phase — when a new session starts (or after compaction), the plugin loads the knowledge JSONL and the handoff state. Claude receives the accumulated knowledge as context, reads the task state, and continues exactly where it left off.

The Flow

Think of it as a relay race. The first runner (pre-compaction session) carries the baton as far as it can. Before hitting the wall, it writes down everything it knows and passes the baton. The second runner (post-compaction session) picks up the baton, reads the notes, and keeps running.

Session start
  |
  v
Work + learn conventions + discover patterns
  |
  v
~90% context reached
  |
  v
[Auto Handoff: save knowledge + write state]
  |
  v
Compaction happens (old messages dropped)
  |
  v
[Auto Handoff: load knowledge + read state]
  |
  v
Resume work with accumulated knowledge

The knowledge file grows across sessions. Information discovered in session one is available in session five. Over time, this creates a rich project memory that makes every session more effective than the last.

What Gets Saved

Not everything is worth saving. Auto Handoff filters for high-value knowledge:

• Conventions — naming patterns, file organization rules, code style preferences
• Decisions — architectural choices, tradeoffs considered, alternatives rejected
• Edge cases — gotchas, workarounds, platform-specific behavior
• Relationships — which files depend on each other, which components interact

Low-value content — greetings, clarification questions, intermediate reasoning — is excluded. This keeps the knowledge file lean and relevant.

Enabling Auto Handoff

Auto Handoff is enabled by default when you install the Brewcode plugin. Verify it is active:

/brewcode:status

Look for handoff: active in the output. If you want to inspect the saved knowledge:

cat .claude/knowledge/entries.jsonl

Each line is a JSON object with timestamp, category, and content fields. You can edit this file manually to correct or add entries.

Auto Handoff pairs especially well with the /brewcode:plan skill. Plans that span multiple compaction cycles now complete reliably because the execution state is preserved across boundaries.