Feature Request: Automatic Context Restoration After Autocompaction

Status Fixed / completed

Maintainer reply ✓ Yes — dicksontsai

Activity 11 comments · opened Aug 18, 2025 · closed Aug 22, 2025

💡 Likely answer: A maintainer (dicksontsai, collaborator) responded on this thread — see the highlighted reply below.

Summary

Add functionality to automatically restore context after autocompaction by re-reading CLAUDE.md and the latest JSONL conversation history file.

Problem Statement

When Claude Code performs autocompaction to manage conversation length, valuable context is lost including:

Project goals and requirements from CLAUDE.md
Recent conversation history and decisions made
Work progress and current state

This forces users to manually re-explain project context and recent work, reducing productivity in long coding sessions.

Use Case

During extended development sessions, developers often hit conversation length limits. Currently, after autocompaction:

Claude loses awareness of project-specific instructions in CLAUDE.md
Recent work context disappears
Users must manually re-establish context
Productivity is disrupted

Proposed Solution

Implement a post-compaction hook that automatically:

Re-reads CLAUDE.md to restore project-level context
Loads latest JSONL conversation history from ~/.claude/projects/
Restores conversation context by providing a summary of recent interactions
Maintains conversation continuity without manual intervention

Implementation Details

Core Components

Context Restorer Class

Handles reading CLAUDE.md from project directory
Finds and parses latest JSONL conversation file
Generates context restoration summary

Autocompaction Hook

Triggers automatically after compaction occurs
Integrates with existing compaction workflow
Provides fallback handling if restoration fails

Integration Points

Modify existing compaction function to call post-compaction hook
Add configuration option to enable/disable feature
Include restoration status in compaction logging

Benefits

Improved Developer Experience: Seamless continuation of work after compaction
Reduced Friction: No need to manually re-explain context
Better Continuity: Maintains project awareness across compaction boundaries
Time Savings: Eliminates repetitive context re-establishment

Alternatives Considered

Manual context reload command: Requires user intervention
Larger context windows: Hardware/cost limitations
More aggressive summarization: May lose important details

Additional Context

This feature would be particularly valuable for:

Long debugging sessions
Complex refactoring work
Multi-file feature implementations
Extended pair programming sessions

Acceptance Criteria

[ ] Context automatically restored after autocompaction
[ ] CLAUDE.md contents available post-compaction
[ ] Recent conversation summary provided
[ ] Feature can be enabled/disabled via settings
[ ] Restoration failures handled gracefully
[ ] Performance impact minimal (<1 second)

Related Issues

Related to context management improvements
Complements existing autocompaction feature

View original on GitHub ↗

11 Comments

github-actions[bot] · 1 year ago

Found 3 possible duplicate issues:

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

coygeek · 1 year ago

Hey, this is a fantastic and well-thought-out feature request. I've definitely felt this pain point myself during long coding sessions. Losing the CLAUDE.md context and the recent conversation flow after an auto-compaction event is a real productivity killer.

It looks like you're on the right track with the idea of a hook. The docs mention a PreCompact hook (en/docs/claude-code/hooks), which runs before the compaction happens. It gets triggered for both manual and automatic compactions. This is close, but it's not quite the "post-compaction" hook you're proposing, which is what we'd really need to restore context after the fact. A dedicated PostCompact hook would be the ideal solution here.

While we wait for an official feature like that, I was thinking about a potential workaround using the existing hook system. It's a bit of a hack, but it might work.

We could use the UserPromptSubmit hook. This hook runs every time you submit a new prompt. Here's the theory:

Create a UserPromptSubmit hook script. This could be a small Python or shell script.
Inside the script, it would receive the transcript_path via stdin.
The script would then read the conversation log (.jsonl file) and check if the last few entries indicate that a compaction just occurred.
If a compaction was detected, the script would:

Read the contents of all relevant CLAUDE.md files (project and user-level).
Maybe even grab the last 5-10 messages from the transcript to create a quick summary.
Combine this into a context-restoring message like: "SYSTEM NOTE: Context may have been lost due to compaction. Restoring key project context from CLAUDE.md and summarizing recent activity..."

The script would then print this message to stdout and exit with code 0. According to the docs (en/docs/claude-code/hooks), for UserPromptSubmit hooks, stdout is injected directly into the context for Claude to see.

It's not as clean as a dedicated PostCompact hook because it would only trigger on your next prompt after compaction, but it would automate the re-injection of that crucial context without you having to do it manually.

Again, this is just a workaround. Your original proposal for a true PostCompact hook is definitely the better long-term solution. Adding a +1 to this idea

SDS-Mike · 1 year ago

Thanks!

I have also noticed that when I DO remember to catch myself before I hit autocompact, I prompt with:

We are at 5% until autocompact. Create a succinct checkpoint so I can compact safely.

Claude creates an updated todo and progress summary, and tells me it's safe to compact.

/compact

When compaction is complete, I prompt "resume" and we carry on as if nothing happens, and context seems to have been preserved.

Thank you,

[cid:ffb336bc-832f-4283-8557-3328f0ed7e16]<http://www.sequeldata.com/>

Mike Morris | Solutions Architect

11824 Jollyville Rd. Ste. 400 | Austin, Texas 78759
Office: 512.918.8841 | Direct: 512.994.3553

________________________________
From: Coy Geek @.*>
Sent: Tuesday, August 19, 2025 6:11 PM
To: anthropics/claude-code @.*>
Cc: Mike Morris @.>; Author @.>
Subject: Re: [anthropics/claude-code] Feature Request: Automatic Context Restoration After Autocompaction (Issue #6066)

Shadow IT Email Protection
Warning: The sender @@.***.com might be a spam sender.
Block as Spam<https://cloud.graph.us/feedback?msgId=PGFudGhyb3BpY3MvY2xhdWRlLWNvZGUvaXNzdWVzLzYwNjYvMzIwMzcyOTU4NEBnaXRodWIuY29tPg%3D%3D&orgDomain=c2VxdWVsZGF0YS5jb20%3D&sndr=OVl1R21DazZRdHZCQXlxdDV2Y29YV2taa0xEdWRCa1VrTHkxVDlFRzJtbjgrdEJFSnBSd0FnPT0%3D&rcpnt=QWR4VEdzL3BFcE5GQXBqdlVHMUMxTFBmdEJ0eDJyZXA3TnNTRGtPUHlkT25FekFkMXpCWE1nPT0%3D&opt=spam> Not a Spam Sender<https://cloud.graph.us/feedback?msgId=PGFudGhyb3BpY3MvY2xhdWRlLWNvZGUvaXNzdWVzLzYwNjYvMzIwMzcyOTU4NEBnaXRodWIuY29tPg%3D%3D&orgDomain=c2VxdWVsZGF0YS5jb20%3D&sndr=OVl1R21DazZRdHZCQXlxdDV2Y29YV2taa0xEdWRCa1VrTHkxVDlFRzJtbjgrdEJFSnBSd0FnPT0%3D&rcpnt=QWR4VEdzL3BFcE5GQXBqdlVHMUMxTFBmdEJ0eDJyZXA3TnNTRGtPUHlkT25FekFkMXpCWE1nPT0%3D&opt=notaspam>
powered by Graphus®
[https://avatars.githubusercontent.com/u/65363919?s=20&v=4]coygeek left a comment (anthropics/claude-code#6066)<https://github.com/anthropics/claude-code/issues/6066#issuecomment-3203729584>

Hey, this is a fantastic and well-thought-out feature request. I've definitely felt this pain point myself during long coding sessions. Losing the CLAUDE.md context and the recent conversation flow after an auto-compaction event is a real productivity killer.

It looks like you're on the right track with the idea of a hook. The docs mention a PreCompact hook (en/docs/claude-code/hooks), which runs before the compaction happens. It gets triggered for both manual and automatic compactions. This is close, but it's not quite the "post-compaction" hook you're proposing, which is what we'd really need to restore context after the fact. A dedicated PostCompact hook would be the ideal solution here.

While we wait for an official feature like that, I was thinking about a potential workaround using the existing hook system. It's a bit of a hack, but it might work.

We could use the UserPromptSubmit hook. This hook runs every time you submit a new prompt. Here's the theory:

Create a UserPromptSubmit hook script. This could be a small Python or shell script.
Inside the script, it would receive the transcript_path via stdin.
The script would then read the conversation log (.jsonl file) and check if the last few entries indicate that a compaction just occurred.
If a compaction was detected, the script would:

Read the contents of all relevant CLAUDE.md files (project and user-level).
Maybe even grab the last 5-10 messages from the transcript to create a quick summary.
Combine this into a context-restoring message like: "SYSTEM NOTE: Context may have been lost due to compaction. Restoring key project context from CLAUDE.md and summarizing recent activity..."

The script would then print this message to stdout and exit with code 0. According to the docs (en/docs/claude-code/hooks), for UserPromptSubmit hooks, stdout is injected directly into the context for Claude to see.

It's not as clean as a dedicated PostCompact hook because it would only trigger on your next prompt after compaction, but it would automate the re-injection of that crucial context without you having to do it manually.

Again, this is just a workaround. Your original proposal for a true PostCompact hook is definitely the better long-term solution. Adding a +1 to this idea

—
Reply to this email directly, view it on GitHub<https://github.com/anthropics/claude-code/issues/6066#issuecomment-3203729584>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AMNMR2PEPYHRAIVQ7JG2NDD3OPDM3AVCNFSM6AAAAACEGKXY7KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTEMBTG4ZDSNJYGQ>.
You are receiving this because you authored the thread.Message ID: @.***>

SDS-Mike · 1 year ago

I thought about this overnight. You brought up points I was unaware of. Does claude code know, or can it be told to be aware of, the fact that a conversation is nearing autocompaction? If so, those hooks could be used to trigger the automatic setting of a checkpoint, alerting the user of the need to do so and compact safely, then use the post-compact hooks to load the checkpoint file and resume. Ideally this would prevent autocompacting and enable automated SAFE compacting.

Thank you,

[cid:6e5e1402-1e41-4022-9e25-489f8ddc5511]<http://www.sequeldata.com/>

Mike Morris | Solutions Architect

11824 Jollyville Rd. Ste. 400 | Austin, Texas 78759
Office: 512.918.8841 | Direct: 512.994.3553

While we wait for an official feature like that, I was thinking about a potential workaround using the existing hook system. It's a bit of a hack, but it might work.

We could use the UserPromptSubmit hook. This hook runs every time you submit a new prompt. Here's the theory:

Create a UserPromptSubmit hook script. This could be a small Python or shell script.
Inside the script, it would receive the transcript_path via stdin.
The script would then read the conversation log (.jsonl file) and check if the last few entries indicate that a compaction just occurred.
If a compaction was detected, the script would:

Read the contents of all relevant CLAUDE.md files (project and user-level).
Maybe even grab the last 5-10 messages from the transcript to create a quick summary.
Combine this into a context-restoring message like: "SYSTEM NOTE: Context may have been lost due to compaction. Restoring key project context from CLAUDE.md and summarizing recent activity..."

The script would then print this message to stdout and exit with code 0. According to the docs (en/docs/claude-code/hooks), for UserPromptSubmit hooks, stdout is injected directly into the context for Claude to see.

Again, this is just a workaround. Your original proposal for a true PostCompact hook is definitely the better long-term solution. Adding a +1 to this idea

coygeek · 1 year ago

Hey, that's a brilliant follow-up thought. I love how you're thinking about turning a reactive process (recovering from auto-compaction) into a proactive one (managing compaction safely). Your manual workflow of asking for a checkpoint is exactly the right instinct.

You've hit on the key question: "Does Claude Code know... it is nearing autocompaction?"

The answer is yes, it does! You've probably seen the UI warning that pops up when the context window is getting full. The changelog mentions this specifically—in version 1.0.51, they "Increased auto-compact warning threshold from 60% to 80%". So the front-end is definitely aware. The next logical step is to see if we can tap into that awareness with hooks.

I dove back into the docs for the PreCompact hook (en/docs/claude-code/hooks). It's tantalizingly close to what we need. It triggers right before a compaction happens and even tells you if it was manual or auto.

However, there are two key limitations with the current implementation that prevent your ideal automated workflow:

Hooks can't prompt Claude: A hook is a shell script that runs in the background. It can't inject a new prompt into the conversation to ask Claude, "Hey, create a checkpoint for me."
Hooks can't block auto-compaction: The PreCompact hook can't prevent the auto-compaction from happening. According to the docs, even if the hook script exits with an error code, it just shows a message to the user; it doesn't stop the process and give control back to Claude.

So, while we can't fully automate the checkpoint creation, we can absolutely build a more elegant system around your manual process that automates the restoration.

Here’s a refined workflow that combines your idea with the available tools:

---

Proposed "Safe Compaction" Workflow

Step 1: Create a Custom Slash Command for Checkpointing

Instead of typing out the full prompt, let's make it a one-word command. Create a personal slash command file at ~/.claude/commands/checkpoint.md:

---
description: Creates a succinct session checkpoint and saves it to a file.
allowed-tools: Write
---

You are about to perform a safe conversation compaction. Your task is to create a succinct but comprehensive checkpoint of our current session.

The checkpoint should include:
- The main objective we are working towards.
- A summary of the progress made so far.
- An updated list of outstanding tasks or a "todo" list.
- Any key decisions or important context that must be preserved.

After generating the checkpoint summary, use the `Write` tool to save it to the file path `~/.claude/session_checkpoint.md`. Overwrite the file if it already exists.

After saving, confirm by saying "Checkpoint saved. Ready to compact."

Now, when you see the compaction warning, you can just type /checkpoint. Claude will do its thing and save the state.

Step 2: Create a Hook to Restore the Checkpoint Automatically

This is where we can automate the post-compaction part. We'll use the UserPromptSubmit hook we discussed before, but make it smarter. It will look for that checkpoint file, inject it, and then clean up after itself.

Here’s a sample script you could save as ~/.claude/hooks/restore_checkpoint.sh:

#!/bin/bash

CHECKPOINT_FILE="$HOME/.claude/checkpoints/current_session.md"

# Check if the checkpoint file exists
if [ -f "$CHECKPOINT_FILE" ]; then
    # Read the checkpoint content
    CHECKPOINT_CONTENT=$(cat "$CHECKPOINT_FILE")

    # Create the context message to inject
    # This goes to stdout, which the UserPromptSubmit hook adds to Claude's context
    echo -e "SYSTEM NOTE: A compaction occurred. Restoring context from the last checkpoint.\n\n--- CHECKPOINT START ---\n$CHECKPOINT_CONTENT\n--- CHECKPOINT END ---"

    # Clean up the checkpoint file so it doesn't trigger again
    rm "$CHECKPOINT_FILE"

    # Exit with success code 0
    exit 0
fi

# If no checkpoint file, do nothing and exit cleanly
exit 0

Make it executable (chmod +x ~/.claude/hooks/restore_checkpoint.sh) and register it as a UserPromptSubmit hook in your user settings.json.

Step 3: Put It All Together

You're coding, and the "nearing compaction" warning appears.
You run: > /checkpoint
Claude generates the summary and saves it.
You run: > /compact
The conversation is compacted.
You type your next prompt (e.g., > OK, let's continue).
The restore_checkpoint.sh hook runs automatically, finds the checkpoint, injects it into the context for Claude to see, and deletes the file.
Claude now has the restored context and your new prompt, seamlessly continuing the session.

---

This is still a workaround, but it's a much smoother one that automates the most annoying part (the restoration). It turns a disruptive event into a controlled, two-command process.

This whole discussion just reinforces how valuable a true PostCompact hook would be. If we had that, we could combine the checkpoint creation and restoration into a single, seamless background action. Great discussion

ariccio · 1 year ago

Yeah, there's a lot of work that seems like could be done to supercharge this whole process, I poked around the github issues to see if anybody has been thinking along the same lines I have and am glad to see so.

One thing that works astonishingly well for me is pausing once I'm approaching 60%, to ask claude to do something like:

Can you please write ALL the relevant thoughts, reasoning, context, state, and anything else to notes on disk, and then give me a prompt I can copy and paste into a new session of claude code to seamlessly continue this work, without any loss of reasoning ability, details, focus, intelligence, or goal-directed abilities.

Then I copy to the clipboard and compact

After compaction, I paste, making sure to reference the on disk file

I can go on like this ALL day, and lose zero performance. It's wild to me that this isn't implemented natively?

BeekeepingHoneyman · 1 year ago

Thank you. This is thoroughly AWESOME. Now, to repay the AWESOMENESS. Teach your Claude Code destinations using your CLAUDE.md files. Example in use: Definition of INTEGRITY - RELATE that to the SPOKES of a Bicycle Wheel. ONE spoke lose CREATE PROJECT WOBBLE, destroying PROJECT INTEGRITY. BEING INTEGRITY is ROAD LESS TRAVELED it is and ACTION OF, STATE OF BEING INTEGRITY..
see what that adds to your worlds of invention...

BeekeepingHoneyman · 1 year ago

THEORETICAL Implemented a test of the hook that might be interesting. BUILT by CLAUDE CODE PERFECT EXAMPLE OF OVER ENGINEERING

github_issue_6066_comment_draft.md

SDS-Mike · 1 year ago

Awesome thanks! I'll check this out!

Thank you,

[cid:ac657bbe-7399-48ff-a3cc-160a1a53a3de]<http://www.sequeldata.com/>

Mike Morris | Solutions Architect

11824 Jollyville Rd. Ste. 400 | Austin, Texas 78759
Office: 512.918.8841 | Direct: 512.994.3553

________________________________
From: BeeKeeperHoneyman @.*>
Sent: Thursday, August 21, 2025 2:46 PM
To: anthropics/claude-code @.*>
Cc: Mike Morris @.>; Author @.>
Subject: Re: [anthropics/claude-code] Feature Request: Automatic Context Restoration After Autocompaction (Issue #6066)

Shadow IT Email Protection
Warning: The sender @@.***.com might be a spam sender.
Block as Spam<https://cloud.graph.us/feedback?msgId=PGFudGhyb3BpY3MvY2xhdWRlLWNvZGUvaXNzdWVzLzYwNjYvMzIxMjE3MTkzMUBnaXRodWIuY29tPg%3D%3D&orgDomain=c2VxdWVsZGF0YS5jb20%3D&sndr=Y3Zjb212VVlTSVpCWUdIYUtwSjBqb2gyUVNjb2pYWHpIcjZpN3VlVWlmbGd1MldrOUJwTVRnPT0%3D&rcpnt=T2ZqbnFWUXJkRjNlSHlVWVBuVHRIek5YejJaU2JuU3M4TW9WTkJNR3dGOTAyVVB3SU9wTklRPT0%3D&opt=spam> Not a Spam Sender<https://cloud.graph.us/feedback?msgId=PGFudGhyb3BpY3MvY2xhdWRlLWNvZGUvaXNzdWVzLzYwNjYvMzIxMjE3MTkzMUBnaXRodWIuY29tPg%3D%3D&orgDomain=c2VxdWVsZGF0YS5jb20%3D&sndr=Y3Zjb212VVlTSVpCWUdIYUtwSjBqb2gyUVNjb2pYWHpIcjZpN3VlVWlmbGd1MldrOUJwTVRnPT0%3D&rcpnt=T2ZqbnFWUXJkRjNlSHlVWVBuVHRIek5YejJaU2JuU3M4TW9WTkJNR3dGOTAyVVB3SU9wTklRPT0%3D&opt=notaspam>
powered by Graphus®
[https://avatars.githubusercontent.com/u/101668910?s=20&v=4]BeeKeeperHoneyman left a comment (anthropics/claude-code#6066)<https://github.com/anthropics/claude-code/issues/6066#issuecomment-3212171931>

THEORETICAL Implemented a test of the hook that might be interesting. BUILT by CLAUDE CODE

github_issue_6066_comment_draft.md<https://github.com/user-attachments/files/21926601/github_issue_6066_comment_draft.md>

—
Reply to this email directly, view it on GitHub<https://github.com/anthropics/claude-code/issues/6066#issuecomment-3212171931>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AMNMR2M4JEAY5DZXXPOVJ6T3OY42ZAVCNFSM6AAAAACEGKXY7KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTEMJSGE3TCOJTGE>.
You are receiving this because you authored the thread.Message ID: @.***>

dicksontsai collaborator · 1 year ago

Any prompt issued through our query loop has the contents of CLAUDE.md. You can check for this with /context.

Claude loses awareness of project-specific instructions in CLAUDE.md

What you're likely seeing is not that CLAUDE.md is missing after auto-compaction, but rather that Claude is not following your instructions. This is a general model issue that the Claude Code team can't really help with, since it depends on what your instructions are and how ingrained Claude's habits are.

As for what additional context you can add through hooks after compact, consider looking at the SessionStart hook with the compact matcher.

github-actions[bot] · 1 year ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

Feature Request: Automatic Context Restoration After Autocompaction

Summary

Problem Statement

Use Case

Proposed Solution

Implementation Details

Core Components

Integration Points

Benefits

Alternatives Considered

Additional Context

Acceptance Criteria

Related Issues

11 Comments

Proposed "Safe Compaction" Workflow

Related Claude Code issues

Browse by topic