ccsave

Never lose Claude Code session context again.

The Problem

Claude Code sessions hit their context window and /compact destroys your working state. The next session starts cold — no memory of decisions made, files touched, or what you were about to do. ccsave fixes this by snapshotting your session into CLAUDE.md before the context is gone.

Screenshot

Status bar integration coming in Pro — see below.

Installation

npm install -g ccsave

Requires Node.js 18+.

Quick Start

# 1. Set your Anthropic API key (for AI-powered summaries)
ccsave config --api-key sk-ant-...

# 2. Save your first snapshot
ccsave save

# 3. Install hooks (auto-saves before /compact, on session start)
ccsave hooks install

# 4. List snapshots for the current project
ccsave list

Commands

ccsave save

Snapshot the current Claude Code session and inject the summary into CLAUDE.md.

ccsave save                        # AI summary via Haiku (cheap, fast)
ccsave save --no-ai                # Skip AI, use basic file list instead
ccsave save --api-key sk-ant-...   # Override API key for this run

What it does:

• Reads the latest session JSONL from ~/.claude/projects/
• Sends the first 20 + last 40 messages to claude-haiku-4-5 for summarization (~$0.01 per save)
• Writes a structured snapshot block into your project's CLAUDE.md

ccsave restore

Inject a previously saved snapshot back into CLAUDE.md.

ccsave restore                     # Restore the most recent snapshot
ccsave restore --list              # Pick from all saved snapshots interactively
ccsave restore --id <snapshot-id>  # Restore a specific snapshot by ID

ccsave list

Show all saved snapshots for the current project.

ccsave list

Output includes snapshot ID, timestamp, message count, and token estimate.

ccsave config

Configure ccsave settings stored in ~/.ccsave/config.json.

ccsave config --api-key sk-ant-...    # Set Anthropic API key
ccsave config --threshold 2mb         # File size that triggers auto-save
ccsave config --interval 30           # Auto-save interval in minutes (watch mode)
ccsave config --show                  # Print current configuration

Config Options

| Option | Default | Description | |--------|---------|-------------| | apiKey | (none) | Anthropic API key for AI summarization | | fileSizeThreshold | 2mb | Session file size that triggers auto-save in watch mode | | messageCountThreshold | 80 | Message count that triggers auto-save in watch mode | | intervalMinutes | 30 | Polling interval for watch mode | | maxSnapshotsPerProject | 3 | Max snapshots to keep per project (oldest pruned) | | enableWatchLog | false | Write watcher activity to ~/.ccsave/watch.log | | enableNotifications | true | Show system notifications on auto-save |

ccsave hooks install

Register ccsave hooks in ~/.claude/settings.json so saves happen automatically.

ccsave hooks install

Installs two hooks:

• UserPromptSubmit — checks session size on each message; saves when thresholds are crossed
• PreCompact — saves a snapshot immediately before Claude compacts the context

After installing, you never need to run ccsave save manually again.

How It Works

1. ccsave finds your session JSONL file in ~/.claude/projects/<hash>/
2. It windows the transcript (first 20 + last 40 meaningful messages) and sends it to claude-haiku-4-5
3. The AI returns a structured markdown summary (current task, decisions, files touched, next step)
4. The summary is written into a delimited block inside your CLAUDE.md — invisible to normal readers, loaded automatically by Claude Code at session start

The block looks like this in CLAUDE.md:

<!-- [CCSAVE:START] -->
### Current Task
...
<!-- [CCSAVE:END] -->

When you start a new session, Claude Code reads CLAUDE.md and picks up exactly where you left off.

Pro — Coming Soon

The free version covers manual saves and hook-based auto-saves. ccsave Pro will add:

• Watch mode (ccsave watch) — background daemon that polls your session file and auto-saves based on size, message count, and time interval, with no hooks required
• Status bar integration — live token count and last-save time displayed in the Claude Code status bar
• Multi-project dashboard — view all projects and their snapshot history in one place

Sign up for early access: ccsave.dev (coming soon)

Contributing

Bug reports and pull requests are welcome.

git clone https://github.com/olex/ccsave
cd ccsave
npm install
npm run build
npm run dev -- save   # run from source

The source is TypeScript. npm run build compiles to dist/. The entry point is src/index.ts.

Please open an issue before submitting large PRs — it's worth aligning on approach first.

License

MIT — see LICENSE.