How to Restore a Claude Code Project After a Crash

A crash can leave CLAUDE.md as a stub. The repo still builds. The billing rule the agent was following lived in that file, and the file is now wrong.

This is the recovery, run against the SaveState CLI built from this repository at version 0.9.0. The commands were npx --no-install @savestate/cli, linked to that local build, so these transcripts come from this repository. After you install the package, the same subcommands are npx @savestate/cli. The passphrase ledger-crash-demo exists only for this temp project.

For the adapter itself, see Claude Code. Snapshots are a SaveState Archive, encrypted with AES-256-GCM before they are stored.

A project worth restoring

HOME pointed at an empty temp directory, so the Claude Code adapter only read the fixture. The project was two files. CLAUDE.md:

# Ledger

Billing retries must use the idempotency key invoice-replay-7.
Never double-charge a customer after a crash.
Restore this file before the next deploy.

.claude/settings.json allowed Bash(npm test).

$ npx --no-install @savestate/cli --version
0.9.0

Init with the passphrase already set

$ export SAVESTATE_PASSPHRASE='ledger-crash-demo'
$ npx --no-install @savestate/cli init

⚡ SaveState — Time Machine for AI

- Initializing SaveState...
✔ Created .savestate/ directory
- Detecting platform...
✔ Detected platform: Claude Code

  Your snapshots will be encrypted with a passphrase.
  You can also set SAVESTATE_PASSPHRASE env var.


✓ SaveState initialized!

  Next steps:
  savestate snapshot      Capture your first snapshot
  savestate config        Configure storage & adapters
  savestate adapters      See available platform adapters

The Claude Code adapter saw CLAUDE.md. Init took the passphrase from the environment and returned without a prompt.

Snapshot without a passphrase

Clear the variable and snapshot. The command exits 1 and stores nothing.

$ env -u SAVESTATE_PASSPHRASE npx --no-install @savestate/cli snapshot


✗ Snapshot failed
No passphrase available. Set SAVESTATE_PASSPHRASE environment variable or run in an interactive terminal.

Put the passphrase back, then snapshot

$ export SAVESTATE_PASSPHRASE='ledger-crash-demo'
$ npx --no-install @savestate/cli snapshot

- Extracting state via Claude Code adapter...
✔ Full snapshot created!

  ID:         ss-2026-10-17T21-40-56-vpigps
  Adapter:    Claude Code
  Type:       full
  Files:      12 files in archive
  Archive:    1.5 KB
  Encrypted:  1.5 KB
  Storage:    local
  Status:     ✓ Encrypted & stored

  Restore with: savestate restore ss-2026-10-17T21-40-56-vpigps

That archive is ss-2026-10-17T21-40-56-vpigps. Twelve files, 1.5 KB, encrypted, stored locally.

Crash the project file

$ printf 'CORRUPTED AFTER CRASH\n' > CLAUDE.md
$ cat CLAUDE.md
CORRUPTED AFTER CRASH

Restore latest

restore with no id selects the newest snapshot.

$ npx --no-install @savestate/cli restore

🔄 Restoring from snapshot: latest

- Retrieving and decrypting snapshot...
✔ Restore complete!

  Snapshot:      ss-2026-10-17T21-40-56-vpigps
  Timestamp:     2026-10-17T21:40:56.245Z
  Platform:      claude-code
  Adapter:       claude-code
  Identity:      ✓ restored
  Memory:        0 entries restored
  Conversations: 0 indexed

  ✓ Your AI state has been restored.
  Existing files were backed up with .bak extension.

CLAUDE.md matched the original again. The crashed bytes were kept beside it:

$ cat CLAUDE.md.bak
CORRUPTED AFTER CRASH

$ cat CLAUDE.md
# Ledger

Billing retries must use the idempotency key invoice-replay-7.
Never double-charge a customer after a crash.
Restore this file before the next deploy.

Search still finds the billing rule

$ npx --no-install @savestate/cli search invoice-replay-7

🔍 Searching: "invoice-replay-7"

- Searching across snapshots...
  1 result:

  ss-2026-10-17T 2026-10-17 identity     (88%)
    … ---
# Ledger

Billing retries must use the idempotency key invoice-replay-7.
Never double-charge a customer after a crash.
Restore this…
    identity/personality.md

One hit, in identity/personality.md, score 88%. The idempotency key invoice-replay-7 is in the encrypted archive after the file on disk was overwritten.

---

Questions? See the FAQ or open an issue on GitHub.