save

Save session progress as a structured checkpoint. Like a video game save: captures where you are, what you were doing, and what to do next.

How to execute

Step 1: Detect project

Identify the project using this priority order:

1. Look for .claude-save-config.json in CWD or any parent directory. Read its project.slug and project.name.
2. Check ~/.claude/saves/config.json for a projects mapping that matches the CWD.
3. Use the git repository name (from git rev-parse --show-toplevel).
4. Use the current directory name as a fallback.
5. If ambiguous or CWD is $HOME, ask: "Which project should I save under?"

Convert the slug to kebab-case: lowercase, alphanumeric and hyphens only.

Trivial session check: If the session was only Q&A, a single config tweak, or produced no file output, output:

Skipping save. Session was trivial (no substantive work to checkpoint).

And stop.

Step 2: Gather git state

Run these in the CWD (skip if not a git repo):

git branch --show-current
git log --oneline -1
git status --porcelain

Capture: branch name, last commit (hash + subject), count of dirty files, and the porcelain output lines (max 20).

Step 3: Compose save state from session context

From your conversation context, determine:

• intent (string): What was the user trying to accomplish? Write in past progressive tense. Example: "Implementing JWT authentication for the API endpoints." This answers "what were you in the middle of?" not "what did you finish?"
• files_modified (array): Files created, modified, or deleted. Include a brief description of what changed in each. Use paths relative to the project root.
• decisions (array of strings): Choices made during the session and their rationale. Example: "Used RS256 over HS256 for JWT signing because we need key rotation support."
• next_steps (array of strings): What should happen next, ranked by priority. Be specific and actionable. "Implement the refresh token endpoint in src/auth.ts" not "continue working." Each step should be completable in a single session.
• lessons (array of objects with title/finding/implication): Only if a technical pitfall was solved, a strategic insight was confirmed, or a useful pattern was discovered. Most sessions have zero lessons. Don't force it.
• tags (array of strings): 2-5 descriptive tags for searchability. Examples: "auth", "bugfix", "refactor", "database", "api".