claude-context-saver

Automatic context backup and recovery for Claude Code. Saves your conversation state before auto-compaction wipes it, and helps you recover seamlessly.

The Problem

Claude Code auto-compacts conversations when the context window fills up (~83.5% usage), creating a lossy summary. Specific details — error messages, function signatures, architectural decisions — disappear.

This package monitors token usage in real time and creates structured markdown backups before that happens.

Install

Default — local (this project only)

npx claude-context-saver

Hooks install to .claude/ in the current project directory.

Global (all projects)

npx claude-context-saver -g

Hooks install to ~/.claude/ — active for every project.

Other methods

# Global install via npm
npm install -g claude-context-saver
claude-context-saver            # local (default)
claude-context-saver -g         # global

# Manual / from source
git clone https://github.com/panbergco/claude-context-saver.git
cd claude-context-saver
node setup.mjs                  # local (default)
node setup.mjs -g               # global

Restart Claude Code after installing.

Update

npx claude-context-saver@latest        # local
npx claude-context-saver@latest -g     # global

Re-running the installer overwrites hooks with the latest version.

Uninstall

# Local
npx claude-context-saver -u

# Global
npx claude-context-saver -g -u

How It Works

StatusLine Monitor

Runs every turn. Reads token usage from Claude Code and displays a live status line:

[!] Opus 4.6 | 65k/200k | 32% used | 51% free -> backup-3.md

The status line is the only mechanism in Claude Code that provides real-time context visibility.

Dual Triggers

Token-based (primary):

• First backup at 50K tokens, then every 10K (60K, 70K, 80K...)
• Works identically across all context window sizes

Percentage-based (safety net):

• 30% free-until-compaction (~60K tokens remaining)
• 15% free (~30K tokens)
• 5% free (~10K tokens)
• Continuous backup below 5%

The visible "remaining percentage" includes a fixed 33K auto-compaction buffer you can't use. The calculation adjusts for this:

freeUntilCompact = (windowSize - tokensUsed - 33000) / windowSize * 100

PreCompact Hook

Fires right before compaction as a final safety net. Synchronously reads the full conversation transcript before compaction can modify it.

Backups

Numbered markdown files saved to {project}/.claude/backups/:

1-backup-2026-03-07-14-15.md
2-backup-2026-03-07-15-30.md
3-backup-2026-03-07-16-45.md

Each backup contains:

• User requests
• Files modified (Write/Edit paths)
• Tasks created/updated
• Skills invoked
• Bash commands run
• Key assistant responses
• Token state at time of backup

On a long session you'll have many snapshots captured throughout — not just one lossy summary from compaction.

Recovering Context

Every backup also writes to .claude/backups/LATEST.md — a predictable path that never changes.

Automatic (default for local installs)

The installer adds a mandatory instruction to your project's CLAUDE.md:

## Context Recovery (MANDATORY)
IMPORTANT: At the start of every response after context compaction, you MUST immediately
read `.claude/backups/LATEST.md` using the Read tool. This file contains structured
session history that was lost during compaction. Do NOT skip this step.

After compaction, Claude Code reloads CLAUDE.md into context. Claude sees the instruction and reads LATEST.md automatically. No user intervention needed.

Manual: fresh start

If you prefer a clean slate:

/clear
Read .claude/backups/LATEST.md and continue where we left off.

Manual: continue in session

After compaction, tell Claude:

Read .claude/backups/LATEST.md to recover context.

File Layout After Install

Local mode (default) — {project}/.claude/

your-project/
└── .claude/
    ├── hooks/context-saver/
    │   ├── backup-core.mjs
    │   ├── statusline-monitor.mjs
    │   └── conv-backup.mjs
    ├── settings.json                  (statusLine + PreCompact hook added)
    └── backups/
        ├── LATEST.md                      (always the newest backup)
        ├── 1-backup-2026-03-07-14-15.md
        └── 2-backup-2026-03-07-15-30.md

Global mode (-g) — ~/.claude/

~/.claude/
├── hooks/context-saver/
│   ├── backup-core.mjs
│   ├── statusline-monitor.mjs
│   └── conv-backup.mjs
├── settings.json                      (statusLine + PreCompact hook added)
└── claudefast-statusline-state.json   (runtime state)

Settings.json Changes

The installer merges these entries into your settings (all existing settings preserved):

Local (default) uses relative paths:

{
  "statusLine": {
    "type": "command",
    "command": "node \".claude/hooks/context-saver/statusline-monitor.mjs\""
  },
  "hooks": {
    "PreCompact": [{
      "hooks": [{
        "type": "command",
        "command": "node \".claude/hooks/context-saver/conv-backup.mjs\"",
        "async": true
      }]
    }]
  }
}

Global (-g) uses $HOME paths:

{
  "statusLine": {
    "type": "command",
    "command": "node \"$HOME/.claude/hooks/context-saver/statusline-monitor.mjs\""
  },
  "hooks": {
    "PreCompact": [{
      "hooks": [{
        "type": "command",
        "command": "node \"$HOME/.claude/hooks/context-saver/conv-backup.mjs\"",
        "async": true
      }]
    }]
  }
}

Context Window & Compaction

Claude Code auto-compacts at ~83.5% context usage. This is built into Claude Code and cannot be changed. The 33K token buffer is reserved for compaction's own summary.

On a 200K context window:

• ~167K tokens are usable before compaction fires
• The remaining 33K is untouchable buffer
• After compaction, context resets to a lossy summary + system prompt + CLAUDE.md

This tool doesn't prevent compaction — it makes sure you have detailed backups before it happens, and recovers them automatically after.

Requirements

• Node.js >= 18
• Claude Code CLI
• Zero npm dependencies

License

MIT