claude-code-save

A Claude Code skill for session continuity. Save your work like a video game checkpoint, then resume from any new session with full context: intent, progress, decisions, lessons learned, and next steps. Three commands: /save, /load, /saves.

> /save
Saved -- My App (save_1711152000000)
Implementing JWT authentication for the API endpoints
Next: Add refresh token endpoint in src/auth.ts

> /load
=== Previously on: My App ===
Saved 2h ago (manual) on MacBook-Pro
Branch: feature/auth | Last commit: a1b2c3d Add login endpoint

INTENT
Implementing JWT authentication for the API endpoints

PROGRESS
- src/auth.ts (modified) -- Added JWT token generation with RS256
- src/middleware/auth.ts (created) -- Auth middleware for protected routes
- src/auth.test.ts (created) -- Started unit tests (incomplete)

DECISIONS
- Used RS256 over HS256 for JWT signing (need key rotation)

NEXT STEPS
1. Implement the refresh token endpoint in src/auth.ts
2. Finish unit tests in src/auth.test.ts
3. Add rate limiting to the login endpoint

RECENT LESSONS
- jsonwebtoken RS256 requires PEM format keys

=== Ready to continue ===

Three commands:

Command	What it does
/save	Checkpoint your session: intent, files changed, decisions, next steps
/load	Resume from a save with a "Previously on..." briefing
/saves	Browse and search past saves across projects

Plus a SessionEnd hook that auto-saves on every session exit as a safety net.

Install

git clone https://github.com/andrew-shwetzer/claude-code-save.git
cd claude-code-save
./setup.sh

That's it. The installer copies commands, hook, and scripts to ~/.claude/ and creates a default config.

How it works

/save

When you run /save, Claude:

1. Detects your project from the working directory (via config, git repo name, or directory name)
2. Captures git state: branch, last commit, uncommitted changes
3. Writes a structured JSON save to ~/.claude/saves/<project>/ with:
   • What you were working on (intent)
   • Files you changed and what changed in each
   • Decisions you made and why
   • Specific next steps, ranked by priority
   • Lessons learned (if any)
   • Tags for searchability
4. Writes human-readable markdown to a daily progress file (backwards compatible)
5. Appends to a search index for fast lookups

/load

The killer feature. When you start a new session and run /load:

1. Finds the most recent save for your current project
2. Reads the structured save state
3. Checks what changed since the save (new commits, branch changes, uncommitted files)
4. Outputs a scannable "Previously on..." briefing
5. Loads project lessons into context
6. You're immediately ready to pick up where you left off

You can also load by project (/load my-app) or by save ID (/load save_1711152000000).

/saves

Browse your save history:

> /saves
=== Session Saves ===

ID                     Project        When          Type    Intent
save_1711152000000     my-app         2h ago        manual  Implementing JWT auth
save_1711148400000     my-app         3h ago        auto    (session exit)
save_1711134000000     api-server     yesterday     manual  Fixing rate limiter bug

Showing 3 of 3 saves across 2 projects.
/saves <project> -- filter by project | /saves search "query" -- search

Filter by project (/saves my-app) or search (/saves search "database migration").

Project detection

Your project is detected automatically, in this priority order:

1. .claude-save-config.json in your project root (most reliable):

   {"project": {"slug": "my-app", "name": "My App"}}

2. ~/.claude/saves/config.json path mappings:

   {
     "projects": {
       "my-app": ["~/projects/my-app"],
       "api": ["~/work/api-server"]
     }
   }

3. Git repo name (from git rev-parse --show-toplevel)

4. Directory name (fallback)

Configuration

Config lives at ~/.claude/saves/config.json (created by setup):

{
  "max_saves_per_project": 50,
  "projects": {},
  "sync": {
    "enabled": false
  },
  "markdown_progress": {
    "enabled": true,
    "directory": "~/Desktop/Claude Completed Tasks"
  }
}

Setting	Default	Description
max_saves_per_project	50	Old saves auto-pruned when limit is exceeded
projects	{}	Map project slugs to directory patterns
sync.enabled	false	Auto-push/pull saves via git for cross-machine sync
markdown_progress.enabled	true	Write human-readable daily markdown files
markdown_progress.directory	~/Desktop/Claude Completed Tasks	Where markdown goes

File layout

~/.claude/
  commands/
    save.md                    # /save command
    load.md                    # /load command
    saves.md                   # /saves command
  hooks/
    save-progress.sh           # SessionEnd auto-save hook
  saves/
    config.json                # Configuration
    index.jsonl                # Search index (append-only)
    schema/
      save-state.schema.json   # JSON Schema reference
    scripts/
      detect-project.sh        # Project detection logic
    my-app/                    # Per-project save directories
      20250323_143000.json     # Individual save states
      lessons.md               # Project lessons (append-only)
    api-server/
      20250322_091500.json
      lessons.md

Save state schema

Each save is a self-contained JSON file. See schema/save-state.schema.json or examples/save-state.json for the full structure.

Key fields:

Field	Description
intent	What you were in the middle of (not what you finished)
files_modified	Files changed with action type and description
decisions	Choices made and their rationale
next_steps	Specific, actionable items ranked by priority
lessons	Technical pitfalls, insights, patterns (rare, timeless)
git	Branch, last commit, uncommitted changes
tags	Free-form labels for search

Cross-machine sync

Save on your laptop, /load on your desktop. Sync uses a private git repo as the transport.

Setup:

# During install:
./setup.sh --sync git@github.com:you/claude-saves-private.git

# Or add sync to an existing install:
cd ~/.claude/saves
git init
git remote add origin git@github.com:you/claude-saves-private.git
git push -u origin main

Then set sync.enabled to true in ~/.claude/saves/config.json:

{
  "sync": {
    "enabled": true
  }
}

How it works:

• /save and the SessionEnd hook auto-commit and push after writing saves
• /load auto-pulls before reading saves
• Conflict-free by design: each save is its own file (timestamped), and index.jsonl is append-only
• If the network is down, saves are stored locally and sync on the next push
• config.json is gitignored (machine-specific settings stay local)

Requirements: A private git remote. GitHub, GitLab, Bitbucket, or a bare repo on your own server all work. Use a private repo since saves contain file paths and session context.

Customization

Custom progress directory: Change markdown_progress.directory in config.json.

Disable markdown output: Set markdown_progress.enabled to false if you only want JSON saves.

Per-project config: Drop a .claude-save-config.json in any project root for reliable detection in monorepos.

Requirements

• Claude Code CLI
• Python 3 (used by the hook for JSON handling)
• macOS or Linux
• Git (optional, for git state capture)

License

MIT