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 claude-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.