[FEATURE] Auto-save project state before context compaction

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

During long work sessions, when the conversation context approaches the token limit (~200k), Claude Code automatically compacts the conversation to continue working. However, this compaction can result in loss of important details and work context, forcing users to manually recreate or re-explain previously covered information.

Currently, users must remember to manually save their work state before context saturation, which is:

• Not obvious - users don't monitor token usage actively
• Inconsistent - easy to forget during focused work
• Risky - can lead to lost context and duplicated effort

Proposed Solution

see general description

Alternative Solutions

Automatically trigger a full project state save when context usage exceeds ~75% (150k/200k tokens), before the automatic compaction occurs.

The auto-save should include:

1. Update/create PROJECT_STATE.md with:

• Current session summary
• Work completed
• Current state
• Next steps

1. Git commit of all changes (if in a git repo)
2. Git push to remote (if configured)
3. Update resume_session.txt with command to resume conversation
4. Notify user: "Context approaching limit - project state saved automatically"

Priority

High - Significant impact on productivity

Feature Category

Other

Use Case Example

_No response_

Additional Context

Benefits

For Users:

• ✅ Guaranteed continuity - no context loss across compactions
• ✅ Zero cognitive load - no need to monitor token usage
• ✅ Automatic backups - work always saved before compaction
• ✅ Resume capability - can always pick up where left off

For Claude Code:

• ✅ Better UX - users never lose work progress
• ✅ Reduced frustration - eliminates "where were we?" moments
• ✅ Professional workflow - automatic state management like modern IDEs
• ✅ Scalable to long sessions - supports complex, multi-hour projects

Real-World Use Case

Context: Multi-hour session working on a music chord database project (BandBook)

What happened:

• Session involved: database expansion (327→443 chords), implementing new features, fixing bugs, analyzing files
• Reached ~125k/200k tokens (62% usage)
• User realized context compaction could lose critical details
• Had to manually implement auto-save as a custom memory directive

What should have happened:

• At ~150k tokens, Claude Code automatically saves project state
• User notified: "Context usage 75% - project state saved"
• Compaction can occur safely with full state preserved in git + markdown files
• Next session starts by reading saved state files

Implementation Suggestions

Trigger Points:

• Primary: 150k tokens (75% of 200k)
• Secondary: Before any automatic compaction
• Optional: User-configurable threshold in settings

What to Save:

# Auto-generated by Claude Code - Session State

**Last Updated**: 2026-06-01 14:30 UTC
**Context Usage**: 150k/200k tokens (75%)
**Reason**: Auto-save before compaction

## Session Summary
[What was accomplished this session]

## Current State
[Project status, files modified, features added]

## Next Steps
[What to do next, pending tasks]

## Command to Resume
claude --resume <conversation-id>

Settings Integration:

{
  "autoSave": {
    "beforeCompaction": true,
    "tokenThreshold": 150000,
    "includeGitCommit": true,
    "includeGitPush": true,
    "stateFileName": "CLAUDE_STATE.md"
  }
}

Current Workaround

Users can manually implement this via memory directives:

Before context compaction (when >150k tokens):
1. Update STATO.md
2. git commit
3. git push
4. Update resume_session.txt
5. Notify user

However, this requires:

• Manual setup per project
• Understanding of Claude Code's memory system
• Custom scripting/configuration

It should be a default feature, not a workaround.

Expected Behavior

Scenario 1: Long session (no git)

• User works for 3 hours, reaches 150k tokens
• Claude: "Context usage 75% - saving project state..."
• Creates/updates CLAUDE_STATE.md with session summary
• Claude: "✅ State saved. Continuing work..."
• Compaction occurs safely

Scenario 2: Long session (with git)

• User works for 3 hours, reaches 150k tokens
• Claude: "Context usage 75% - saving and committing..."
• Updates CLAUDE_STATE.md
• git add . && git commit -m "Auto-save: session state before compaction"
• git push (if remote configured)
• Claude: "✅ Committed and pushed. Continuing work..."

Scenario 3: Resume after compaction

• User starts new session
• Claude automatically reads CLAUDE_STATE.md from previous session
• Claude: "Last session: expanded database to 443 chords, implemented grading system. Ready to continue."

Related Features

This complements existing Claude Code features:

• /remember - stores facts, but not comprehensive state
• CLAUDE.md - static project docs, not session state
• Memory system - stores directives, not work history

Auto-save fills the gap: comprehensive, automatic, session-aware state preservation.

Priority

High - This directly impacts user trust and productivity in long sessions, which are increasingly common as Claude Code is used for complex, real-world projects.

Additional Notes

This feature would position Claude Code as a truly professional development environment, on par with modern IDEs that auto-save and maintain session state automatically.

Users shouldn't have to think about context management - it should just work.

---

Submitted by: User working on complex music notation project (6+ hour session, 443-chord database)
Version: Claude Sonnet 4.5 / Claude Code
Platform: Linux (Ubuntu-based)