Lightweight Session Save/Resume

Save the current working state as a compact, self-contained markdown document. Resume later by loading it into a new conversation. The session file represents current state only — each save overwrites the previous version, pruning resolved items to stay small.

Storage location: ~/.claude/session-logs/<slug>.md

Argument Dispatch

Parse the first word of $ARGUMENTS:

Save Mode

Step 1 — Determine Context

1. Run pwd via Bash. Store the result, replacing the literal home directory with ~ (e.g. ~/my-code/app not /Users/jane/my-code/app).
2. Check for existing session files:

   ls -1t ~/.claude/session-logs/*.md 2>/dev/null

3. Sessions exist: list them (slug, working_dir, last_updated) and ask: "Found these existing sessions. Update one of them, or start a new session?" Do not auto-match by working_dir — the user may be in a different clone or worktree of the same repo. Let them pick.
4. User picks an existing session: read it — this is the starting point for the update. Update its working_dir to the current directory.
5. No sessions exist, or user chooses "new": proceed as a new session.

Step 2 — Propose Content

Based on everything known from the current conversation, draft content for three sections and present the proposal to the user:

1. General Context — Background about the repo: what it is, how its parts interact, architecture relevant to the work. This section changes rarely; carry it forward across saves.
2. Project-Specific Context — What the current work is about: key concepts, patterns, and approaches being used. Evolves session to session.
3. Where We Left Off (optional) — In-progress work, next steps, blockers, pending decisions. Most volatile section; makes resume actionable. Omit if the user is saving mid-exploration with no clear next step.

When updating an existing session:

• Review each section against what happened in this conversation.
• Prune resolved bugs, completed tasks, and obsolete context.
• Add newly discovered context.
• Rewrite "Where We Left Off" to reflect the current state.

Present the proposal:

Here's what I'd capture for this session:

General Context: [proposed content]

Project-Specific Context: [proposed content]

Where We Left Off: [proposed content]

What would you add, remove, or change?

Step 3 — Refine Interactively

Iterate with the user until they confirm:

• Accept additions, removals, and rewrites.
• All file paths must be relative to the repo root — no absolute paths.
• The document must be self-contained: store extracted content, never reference external documents (PRDs, checkpoints) as load-time dependencies.
• If unsure whether something is still relevant, ask.
• Keep total content under ~4k tokens. If a section grows large, summarize.

Step 4 — Write Session File

New sessions:

1. Generate a slug: lowercase, hyphens, 3–5 words from the topic, with date appended as -YYYY-MM-DD. Example: native-menus-bugfixes-2026-04-05.
2. Check for collision: if ~/.claude/session-logs/<slug>.md exists, append -2, -3, etc.
3. Set both created and last_updated to the current UTC timestamp.

Existing sessions:

1. Preserve the original created timestamp.
2. Update last_updated to the current UTC timestamp.

All sessions:

1. mkdir -p ~/.claude/session-logs
2. Write (or overwrite) ~/.claude/session-logs/<slug>.md using the format below.
3. Confirm: "Session saved to ~/.claude/session-logs/<slug>.md."

List Mode

1. Find session files:

   ls -1t ~/.claude/session-logs/*.md 2>/dev/null

2. If none found: "No saved sessions found in ~/.claude/session-logs/." Stop.
3. For each file, read the YAML frontmatter to extract slug, working_dir, and last_updated.
4. Present as a list:

   Available sessions:
   - native-menus-bugfixes-2026-04-05 — ~/my-code/electron-app (updated 2026-04-05)
   - auth-refactor-2026-03-28 — ~/my-code/backend (updated 2026-03-30)

5. Ask which session to resume. If the user picks one, proceed to Load Mode with that file path.

Load Mode

1. Read the session file at the given path. If it does not exist, report the error and stop.
2. Run pwd via Bash and compare to working_dir from frontmatter.
3. If they differ, note it but do not block: "This session was saved in <stored_dir> but you're currently in <current_dir>. File paths in the session are relative to the original project root."
4. Present the full session content — title and each section. Highlight Where We Left Off as the actionable starting point.
5. Ask: "Ready to continue from here, or want to adjust anything first?"
6. STOP. Wait for the user's explicit confirmation before beginning any work. The user may want to correct outdated information, adjust the plan, or provide additional context.

Session File Format

---
slug: <slug>
working_dir: <path with ~ for home>
created: <YYYY-MM-DDTHH:MM:SSZ>
last_updated: <YYYY-MM-DDTHH:MM:SSZ>
---

# <Session Title>

## General Context

<Repo background, architecture, how parts interact.
Write once, carry forward across saves.>

## Project-Specific Context

<Current work: key concepts, patterns, approaches.
Evolves session to session.>

## Where We Left Off

<Optional. In-progress work, next steps, blockers, pending decisions.
Most volatile — rewritten each save.>

Guidelines

• Under 4k tokens. The whole point is a small context footprint on resume. If content grows, summarize harder.
• Self-contained. Include extracted content directly. Never store pointers to external documents as dependencies.
• Relative paths only. All file paths relative to repo root — ensures cross-clone compatibility.
• Current state, not history. Each save overwrites. Prune completed tasks, resolved bugs, and dead context.
• Source-agnostic. Capture whatever is known at save time — from PRDs, from conversation, from code exploration. The source doesn't matter.
• One session per project. The user typically has one active session per project. When saving, present existing sessions and let the user choose which to update — do not auto-match by working_dir, since the user may work from different clones or worktrees.

Privacy

• Always use ~ instead of the expanded home directory path.
• Never include absolute paths containing usernames in the session body.
• Never include secrets, API keys, or credentials.