Claude Code 'Compaction Failed': Causes and 3 Fixes

If Claude Code shows “compaction failed, conversation could not be reduced below the context limit”, or simply forgets what you discussed after compaction, the state you needed lived only in the conversation. If you got a different message, such as “summarization failed: generation hit the token cap”, the cause is different and the section on the other compaction errors covers it. This is the context management module of the complete Claude Code guide: a three-file dev-docs system that keeps state outside the chat so you stop paying the rebuild tax every session.

Claude context management is the practice of persisting task state outside the conversation so Claude can resume exactly where it left off after context compaction. The standard method is a three-file system: plan.md (approved strategy), context.md (current state and key decisions), and tasks.md (progress checklist). Before compaction, run /update-dev-docs to save state; after compaction, type “continue” and Claude reads the files automatically, no re-explaining required.

I said it. Claude didn’t remember. Thirty minutes of context-building: file locations, architectural decisions, progress updates, gone after compaction. We were starting over.

I’ve rebuilt context after compaction 40+ times before I fixed it. Each re-explanation averaged 20 minutes. That’s over 13 hours of pure re-work.

The dev docs workflow prevents context amnesia by persisting task state outside the conversation. Three files: plan.md, context.md, tasks.md. They capture everything Claude needs to continue exactly where it left off. After compaction, say “continue” and the AI reads the docs automatically. No re-explaining. No lost progress.

What happens during Claude Code context compaction?

Claude Code context compaction summarizes older conversation history when the active context becomes too large. The session continues, but exact file paths, rejected approaches, implementation decisions, error history, and unfinished steps can disappear from the working context. Compaction is not the same as a model becoming less capable. The model is working from a compressed and incomplete representation of the earlier session.

Information at risk	What failure looks like	Persistent location
Approved architecture	Claude proposes an approach you already rejected	plan.md
Current files and symbols	Claude searches for the same code again	context.md
Completed work	Previously finished steps are repeated	tasks.md
Known errors	Failed approaches are attempted again	context.md
Next action	The resumed session starts from a generic guess	tasks.md

Context compaction is necessary. Conversations grow too long. The AI summarizes older messages to make room for new ones. Claude’s context window documentation details the token limits that make compaction inevitable on long tasks.

The problem is what gets lost:

• File paths you spent time locating
• Decisions you already made together
• Progress state on multi-step tasks
• Specific errors you already debugged

That specific frustration: “we already discussed this.” The kind where you want to rage-quit and start fresh. For me it became a weekly experience.

Here is the compaction math. A 3-hour implementation session hits compaction at roughly 90-120 minutes. If you have no persistence system, you spend 20-30 minutes rebuilding context. That is 25-35% of your session time going backwards.

I write more documentation to write less documentation. Anthropic’s documentation describes how context management and structured prompting directly affect output quality across sessions.

The paradox resolves when you realize re-explaining is the most expensive documentation of all.

How do you prevent context loss from compaction?

Prevent context loss by saving task state outside the conversation before compaction occurs. Keep the approved approach in plan.md, current files and decisions in context.md, and completed plus remaining work in tasks.md. Update those files after material decisions, not only when the context window is already full. After compaction, reload the three files before continuing implementation.

What Are the Three Dev Doc Files?

The three dev doc files are plan.md, context.md, and tasks.md. Each task gets its own directory containing all three. Plan.md holds the approved implementation strategy. Context.md tracks current state, key files, and blockers. Tasks.md is a granular checklist with completion status. Together they persist everything Claude needs to resume after compaction.

Every non-trivial task gets a directory:

~/dev/active/[task-name]/
├── [task-name]-plan.md
├── [task-name]-context.md
└── [task-name]-tasks.md

plan.md: The Approved Blueprint

The implementation plan, approved before coding begins.

# Feature: User Authentication

## Approach
JWT-based auth with refresh tokens. Store in httpOnly cookies.

## Files to Modify
- src/routes/api/auth/+server.ts (create)
- src/lib/auth/jwt.ts (create)
- src/hooks.server.ts (modify)

## Decisions Made
- Chose JWT over sessions for stateless scaling
- 15-minute access token, 7-day refresh token
- No third-party auth initially

This file doesn’t change during implementation. It’s the reference point.

context.md: The Living State

Current progress, key findings, blockers. Updated frequently.

# Authentication - Current Context

## Progress
- [x] JWT utility created
- [x] Login endpoint working
- [ ] Refresh token rotation
- [ ] Protected route middleware

## Key Files
- src/lib/auth/jwt.ts:45 - Token generation
- src/routes/api/auth/login/+server.ts - Working endpoint

## Current State
Stuck on refresh token rotation. The cookie isn't being
set correctly in the response. See error at line 78.

## Next Steps
1. Debug cookie setting in +server.ts
2. Test with browser dev tools
3. Implement rotation logic

This is what Claude reads after compaction. It knows exactly where you are.

tasks.md: The Checklist

Granular work items with status.

# Authentication Tasks

## Phase 1: Core Auth
- [x] Create JWT utility functions
- [x] Implement login endpoint
- [x] Add password hashing
- [ ] Implement refresh rotation
- [ ] Add logout endpoint

## Phase 2: Protected Routes
- [ ] Create auth middleware
- [ ] Protect /dashboard routes
- [ ] Add redirect to login

## Phase 3: UI
- [ ] Login form component
- [ ] Error handling
- [ ] Success redirect

Check items as you complete them. Claude sees progress at a glance.

What’s the Complete Dev Docs Workflow?

The complete workflow runs in seven steps: enter plan mode, review the plan thoroughly, interrupt before implementation begins, run /create-dev-docs, implement one or two sections at a time, run /update-dev-docs before compaction, then say ‘continue’ after compaction. Claude reads the saved docs automatically and resumes without any re-explaining.

Here’s the step-by-step process:

1. Enter Plan Mode

Start with planning, not coding. Always.

You: "I need to add user authentication"
Claude: [Enters plan mode, explores codebase]

2. Review the Plan Thoroughly

Catch mistakes before implementation.

You: [Read the plan carefully]
You: "What about rate limiting on login attempts?"
Claude: [Updates plan]

3. Hit ESC Before Implementation

Interrupt Claude before it starts coding.

Claude: "I'll start by creating the JWT utility..."
You: [Press ESC]

This prevents “gun-blazing” implementation without documentation.

4. Run /create-dev-docs

Create the three files from the approved plan.

You: "/create-dev-docs"
Claude: [Creates task directory with plan.md, context.md, tasks.md]

5. Implement 1-2 Sections at a Time

Don’t do everything at once. Review between sections.

You: "Let's implement Phase 1: Core Auth"
Claude: [Implements, updates tasks.md]
You: [Review the code]
You: "Good, continue to Phase 2"

6. Run /update-dev-docs Before Compaction

When you sense context is getting long:

You: "/update-dev-docs"
Claude: [Updates context.md with current state, next steps]

7. After Compaction, Say “Continue”

The magic moment:

[Context compacted]
You: "continue"
Claude: [Reads dev docs automatically, knows exactly where you are]

No re-explaining. No lost context. Just continuation.

Claude Code compaction recovery checklist

1. Stop implementation when the session begins losing exact file or decision recall.
2. Update context.md with current files, decisions, errors, and unresolved questions.
3. Mark completed and remaining work in tasks.md.
4. Confirm that plan.md still represents the approved approach.
5. Start the resumed context by loading all three files.
6. Ask Claude to state the next bounded action before editing.

The same failure mode appears at larger scale in a 36,000-line production codebase, where context loading and pre-compaction handoffs became operating requirements. For long agentic tasks, pair the persistence system with model and effort-tier selection based on workload.

What do the other Claude Code compaction errors mean?

The line at the top of this post is the common one, but Claude Code can stop compaction with several different messages, and they do not all have the same cause. The wording below is what the terminal prints; none of these strings appear in the official documentation, so treat the causes as observed behaviour, not a published contract.

Message	What failed	First thing to try
Compaction failed · Conversation could not be reduced below the context limit	The summary itself would still not fit. The conversation holds more state than one context window can carry.	Move state into the three files above, then /clear and resume from them.
Compaction failed: Summarization failed: generation hit the token cap and the summary is incomplete	The model writing the summary ran out of output room before it finished. The conversation is too dense for one summary pass.	Run /compact with a focus so the summary has less to cover.
Compaction failed: received empty response from model, or Error during compaction: summarization produced empty response	The summarization request returned nothing. This is usually a transient request failure, not a size problem.	Retry /compact once. If it repeats, shrink the recent turn.
Prompt is too long · Automatic compaction failed: summarization produced empty response	The request to summarize was itself over the limit, so the model could not answer at all.	Clear the largest tool output, or /rewind and summarize only part of the session.
Autocompact is thrashing: the context refilled to the limit	Compaction worked, but a file or tool output refilled the window several times in a row, so Claude Code stopped retrying.	Read the oversized file in smaller chunks.

Summarization failed: generation hit the token cap and the summary is incomplete

This variant is the one people search for most after the main error. The summarizer is a model call like any other, and it has an output limit. When a session has many long tool results, the summary that would faithfully cover them is longer than the summarizer is allowed to write, so the pass is cut off and Claude Code refuses to replace your conversation with a partial summary.

The fix is to reduce what the summary has to hold:

1. Run /compact with an instruction, for example /compact keep only the plan, the diff, and the failing test. The official guide describes the focus form of /compact as the way to choose what the summary keeps.
2. Run /rewind, pick a message, and choose “Summarize up to here” so only the older part of the session is condensed.
3. Send large reads and log trawls to a subagent. Its output stays in a separate context window and only the result comes back.
4. If the session is already in the dev-docs workflow, run /update-dev-docs, then /clear. The files carry the state; the summary no longer has to.

Received empty response from model, or summarization produced empty response

An empty response means the summarization request returned no text. In practice this is most often a transient failure of that one request. Retry /compact once before changing anything. If the empty response repeats, the most recent turn is usually the cause: one enormous tool result can push the summarization request past the limit, which is the “Prompt is too long” form of the same message. Clear that output, or ask Claude to re-read the file in a smaller range, and compact again.

Make compaction happen earlier

Every message above appears when compaction runs late, with the window nearly full. Two documented settings move it earlier. The autoCompactWindow key in settings, or the /autocompact command, sets how full the context gets before Claude Code compacts. The CLAUDE_CODE_AUTO_COMPACT_WINDOW environment variable and the --autocompact flag override it for one session. Compacting at a lower fill leaves the summarizer room to finish.

If the problem is the window size rather than the session shape, the current Fable, Sonnet 5, and Opus models run with a one million token context window on the Anthropic API, and older models take the [1m] suffix in /model. The official model configuration page lists availability by plan. Compaction works the same way at the larger limit, so the three files still matter; the larger window only delays the point at which they are needed.

To check whether long sessions and compaction are where your own plan usage goes, the free Claude Code Runway Audit reads the token counts in your local transcripts and reports how often your sessions hit compaction. It runs on your machine and sends nothing anywhere.

How Does Multi-Root Workspace Structure Help?

Multi-root workspace structure separates context by repository so frontend knowledge doesn’t pollute backend work. Each repo holds its own claude.md for repo-specific instructions, a PROJECT_KNOWLEDGE.md for architecture details, and a TROUBLESHOOTING.md for recurring issues. Claude reads only the files relevant to your current work, keeping context lean and accurate.

For projects with multiple repos:

~/git/project/
├── CLAUDE.md                  # Root config (~100 lines)
├── dev/active/[task-name]/    # Dev docs location
├── frontend/
│   ├── claude.md              # Repo-specific (50-100 lines)
│   ├── PROJECT_KNOWLEDGE.md   # Architecture details
│   └── TROUBLESHOOTING.md     # Common issues
└── backend/
    └── ...

Each repo has its own context files. Claude reads the relevant ones based on which files you’re working with.

Benefits:

• Separation of concerns: Frontend context doesn’t pollute backend work
• Reusable knowledge: PROJECT_KNOWLEDGE.md persists across sessions
• Troubleshooting history: Common issues documented once, used forever

What Do the 16 Automation Hooks Do?

The 16 automation hooks enforce workflow quality without manual intervention. UserPromptSubmit analyzes prompts and activates relevant skills. PreToolUse validates operations before they run. PostToolUse logs every file change. Stop-BuildChecker runs builds automatically on modified repos. Stop-ErrorReminder scans for missed error patterns. Together they catch problems throughout the session without any extra commands. Context-switching is especially costly with ADHD; the Claude Code workflow for ADHD brains builds this persistence in from the start.

Hooks enforce the workflow without manual intervention:

The pipeline runs automatically. You just work. The system catches problems.

When Should I Skip Dev Docs?

Skip dev docs for quick questions, simple single-line fixes, and one-off tasks that fit entirely in a single conversation. Use them for any task taking more than 30 minutes, work spanning multiple sessions, complex features touching multiple files, or anything you would hate to re-explain from scratch after a context compaction event.

Not every task needs the full workflow:

Skip for:

• Quick questions (“How do I X?“)
• Simple fixes (typo, single-line change)
• One-off tasks that fit in one conversation
• Exploration without implementation

Use for:

• Any task taking more than 30 minutes
• Multi-session work
• Complex features with multiple files
• Anything you’d hate to re-explain

The overhead of creating dev docs pays off the first time you avoid context loss.

Context Loss Cost: Before vs. After Dev Docs

These are my actual numbers from 6 months of Claude Code use on a multi-repo SvelteKit project with 16 hooks configured.

Metric	Without Dev Docs	With Dev Docs
Time lost to context re-build per session	20-30 min	0-2 min
Sessions hitting compaction (per week)	4-6	4-6
Total weekly re-explanation overhead	80-180 min	0-12 min
Decision drift (re-debating settled choices)	Weekly	Rare
“Gun-blazing” implementation incidents	2-3/week	0-1/month
Setup cost	0	30 min (one-time)

The break-even is a single session with compaction. After that, dev docs are pure time savings. The 30-minute setup has paid back over 60 hours since I built it.

How Do I Get Started?

Start with the minimum viable setup: create a dev/ directory in your project root, create template files for plan, context, and tasks, then add ‘continue’ handling to your CLAUDE.md so Claude knows to read dev docs on that command. The full setup with hooks and workspace structure adds a few more hours but pays off quickly.

Minimum Viable Setup

1. Create a dev/ directory in your project root
2. Create template files for plan, context, tasks
3. Add “continue” handling to your CLAUDE.md:

## On "continue" command
1. Check for dev/active/*/context.md
2. Read the most recent context file
3. Resume from documented state

Full Setup

1. Install the dev docs commands (slash commands or aliases)
2. Configure hooks for automatic skill activation
3. Set up build checking on Stop events
4. Create workspace structure for multi-repo projects

The full system takes a few hours to configure. But it saves that time on every long task thereafter.

FAQ: Context Management for Claude Code

The questions below cover context compaction, dev doc setup, and when to use the workflow. Short answers are here. The sections above have the full implementation detail.

What is context compaction in Claude? When conversations get too long, Claude summarizes older messages to free up space. This ‘compaction’ loses details: specific decisions, file paths, progress state. The AI continues but forgets what you already discussed.

What are dev docs in Claude Code workflow? Dev docs are three files created for each task: plan.md (approved implementation plan), context.md (key files, decisions, current state), and tasks.md (checklist of work items). They persist outside the conversation.

How does the dev docs workflow prevent context loss? Before compaction, run /update-dev-docs to save current state. After compaction, say ‘continue’ and Claude reads the dev docs automatically, picking up exactly where you left off with full context.

When should I use dev docs vs regular conversation? Use dev docs for any task taking more than 30 minutes or spanning multiple sessions. Skip for quick questions, simple fixes, or one-off tasks that fit in a single conversation.

How do 16 automation hooks fit into this workflow? Hooks automate quality control throughout: UserPromptSubmit activates skills, PostToolUse tracks file edits, Stop-BuildChecker runs builds automatically, Stop-ErrorReminder checks for missed errors. They enforce the workflow without manual intervention.

What does “summarization failed: generation hit the token cap” mean? The model writing the compaction summary ran out of output room before it finished, so Claude Code refused to replace the conversation with a partial summary. Run /compact with a focus instruction, summarize only part of the session with /rewind, or save state to dev docs and /clear.

Why does compaction say “received empty response from model”? The summarization request returned no text. It is usually a transient request failure, so retry /compact once. If it repeats, the most recent turn is probably too large; clear the big tool output or re-read the file in a smaller range, then compact again.

---

The Failure That Caused This

The dev docs system came from a 3-hour session that hit compaction and lost everything: JWT vs. session decision, token lifetimes, cookie configuration. Claude resumed with a completely different approach. I spent 45 minutes reconstructing decisions I had already made. That night I built the first version of the system.

The context amnesia problem came to a head on a specific afternoon.

I was 3 hours into implementing a multi-step authentication flow. We’d made specific decisions: JWT over sessions, 15-minute access tokens, httpOnly cookies, no third-party auth libraries. All of this was in conversation history.

Then context compaction hit.

I typed “continue” and Claude started implementing. A completely different approach. Sessions instead of JWT. localStorage instead of cookies. Not because it was ignoring my instructions. It genuinely didn’t have them anymore.

I spent 45 minutes figuring out what had changed and re-explaining the decisions we’d already made. Some of those decisions were subtle. The 15-minute token lifetime had a specific reason tied to our security requirements. I had to reconstruct the reasoning from scratch.

That night I built the first version of the dev docs system. Three files, 30 minutes to set up. The next session I ran into compaction again. This time I typed “continue” and Claude picked up exactly where we were. The cookies decision. The token lifetime. The files already modified. All of it.

The 30-minute setup has paid off dozens of times since. Context compaction is still annoying. But it’s no longer a crisis.

I thought I could just re-prompt after compaction. Well, it’s more like… I thought my memory was the backup, when I needed an actual backup.

Maybe the goal isn’t longer context windows. Maybe it’s better context persistence: systems that make “we already discussed this” impossible to say. Retrieval-augmented approaches are another direction entirely; the RAG research by Lewis et al. explores how external knowledge retrieval can supplement limited context windows.

Advanced Patterns: Context Files for Different Work Types

The three-file structure is the baseline. For complex or long-running projects, these variants handle situations the baseline doesn’t cover.

API Design Work

When working on API design (endpoints, data schemas, contracts), context.md needs different sections than implementation work.

Add a current endpoint inventory: list every endpoint you’ve defined or are working toward with method, path, and status (designed, implemented, tested). This prevents the duplication problem where you design an endpoint in session one and Claude proposes a slightly different version in session three because it doesn’t know the first one exists.

Add a schema decisions section: capture data shape choices and the reason for them. “Using string for userId instead of number, consistent with Clerk’s user IDs” takes five seconds to write and prevents an hour of confusion when Claude suggests integer IDs.

UI and Component Work

For frontend work, tasks.md needs visual acceptance criteria, not just functional ones. Add a column: “Visual check: [what it should look like at mobile/desktop].” This forces you to define the visual bar before implementation, not after.

Also add a design decisions section to context.md: color tokens used, responsive breakpoints that apply to this component, and any interaction states (hover, focus, disabled) that need to be handled. These are the details that get lost between sessions and cause inconsistency.

Multi-Session Bug Investigation

Bugs that take more than one session to diagnose need a different structure. Replace plan.md with investigation.md: a hypothesis log. List every hypothesis you’ve tested, what you tried, and what you learned. “Hypothesis: race condition in auth middleware. Tested with logs. Result: not the issue. Logs show auth completes before the error.”

This prevents testing the same hypothesis twice across sessions. It is more common than it sounds when you’re working on a complex bug over several days.

Keep context.md but focus it on the error signature: exact error message, stack trace, files involved, reproduction steps. Update it every session with what changed.

Team Projects

When multiple people work with the same context files, context.md needs a contributor section: “Last updated by [name], [date], summary of changes.” This isn’t bureaucracy. It’s the minimum information that prevents one person from undoing another’s documented decisions.

Also agree on update frequency. Individual projects, you update whenever it’s useful. Team projects, agree on a rule: “update before ending every session involving more than one file change.” Shared files need shared maintenance norms.

The baseline three-file structure handles 80% of sessions. These patterns handle the other 20%: the long-running, multi-person, investigative, and visually-complex work where the baseline creates gaps.

---

What Happens at 38,000 Lines: Context Collapse at Scale

At around 15,000 lines, my trading bot stopped fitting in Claude’s context window in any useful way. The model started hallucinating function signatures from files it couldn’t see and citing methods that had been renamed three refactors ago. The tutorials show you the 500-line project; nobody writes about what happens at 38,000 lines in production.

Context collapse doesn’t announce itself. You notice it when Claude starts being confidently wrong about your own code: suggesting imports that don’t exist, referencing variables from a module you restructured two weeks ago. The model isn’t hallucinating in the general sense; it’s confabulating from stale partial context. Deep call graphs make it worse: showing Claude the execution layer in isolation means it’s reasoning about a system it can’t actually see, and it fills the gaps plausibly, which is the dangerous part.

Three disciplines that held at scale, beyond the three-file baseline:

Scoped entry points, not file dumps. Enter via a narrow question with a named scope: “In signal_processor.py, calculate_momentum returns negative values on gap-up candles,” with three files attached, maximum. If I can’t describe the problem in one sentence with three files or fewer, I haven’t isolated the problem yet. The constraint is a forcing function for clarity.

Checkpoint commits as context anchors. Every meaningful working state gets a commit message a model could read cold: refactor: move position sizing to RiskManager, remove from ExecutionEngine, never fix thing. Starting a new session, git log --oneline -10 carries more semantic load than a paragraph of explanation.

Architecture written before code. If I were starting today: write the context map before the first module, and keep modules shallower than feels right. Deep call graphs are context expensive; flat modules with explicit interfaces are easier to scope into a session. The bot’s most maintainable subsystem is the one kept under 400 lines with clean input/output contracts.

The honest limit: context discipline extends your range, it doesn’t eliminate the problem. At 38,000 lines you start making architectural tradeoffs specifically to manage model context. Subsystems a human engineer might integrate stay separated partly because separation makes them easier to work on with Claude. That’s a property of the workflow, not a bug, and knowing it’s a property means you can design around it.

---

Related Reading

This is part of the Complete Claude Code Guide. Continue with:

• Quality Control System - Two-gate enforcement that blocks “should work”
• Evidence-Based Verification - Why confidence without proof fails
• Token Optimization - Save 60% with progressive disclosure
• Deploy Your Agent on DigitalOcean - VPS setup in 5 steps for $6/month

---

WORK WITH ME · CONTEXT DISCIPLINE, INSTALLED

The 3-file system here is the manual version, and every teammate has to remember to run it. I build custom Claude Code pipelines, $2,000 to $5,000, that wire context persistence, verification gates, and session discipline directly into your repo so the whole team gets it automatically, not by habit. See how the engagement works.