description: "Save session state - persist tasks (via TaskList), plan content, and git context. Complementary to /sync."

Save - Session State Persistence

Persist your current session state for later restoration with /sync.

Arguments

$ARGUMENTS

No args: Save current state (tasks, plan, git context)
"notes": Save with descriptive notes
--archive: Archive current plan to PLAN-<date>.md, then save fresh

What It Saves

Data	Source	Destination
Tasks	TaskList API	`.claude/session-cache.json`
Plan content	Conversation context	`docs/PLAN.md`
Git context	`git status/log`	`.claude/session-cache.json`
User notes	Command argument	`.claude/session-cache.json`
Human-readable summary	Generated	`.claude/claude-progress.md`

Execution

Step 1: Capture Task State

Use TaskList and TaskGet to capture full task data:

1. Call TaskList to get all task IDs and summaries
2. For each task, call TaskGet to retrieve:
   - subject (title)
   - description (full details)
   - status (pending, in_progress, completed)
   - blockedBy (dependency IDs)
3. Store as array with index-based dependency mapping

Note: Tasks do not persist across sessions automatically. This is why /save exists.

Step 2: Capture Plan Content

Extract from conversation context:

Goal statements ("I want to...", "We need to...")
Approach discussions ("Option A vs B")
Decisions made ("Let's go with...")
Steps identified ("First... then...")
Open questions
Blockers

Step 3: Capture Git Context

git branch --show-current
git rev-parse --short HEAD
git log -1 --format="%s"
git status --porcelain | wc -l

Step 4: Write Files

.claude/session-cache.json (machine-readable):

{
  "version": "3.0",
  "timestamp": "2025-12-13T10:30:00Z",
  "tasks": [
    {
      "subject": "Set up OAuth credentials",
      "description": "Configure Google OAuth app in GCP console",
      "activeForm": "Setting up OAuth credentials",
      "status": "completed",
      "blockedBy": []
    },
    {
      "subject": "Fix callback URL handling",
      "description": "OAuth callback URL mismatch in production config",
      "activeForm": "Fixing callback URL handling",
      "status": "in_progress",
      "blockedBy": [0]
    },
    {
      "subject": "Add token refresh",
      "description": "Implement JWT refresh token rotation",
      "activeForm": "Adding token refresh",
      "status": "pending",
      "blockedBy": [1]
    }
  ],
  "plan": {
    "file": "docs/PLAN.md",
    "goal": "Add user authentication with OAuth2",
    "current_step": "Step 3: Implement OAuth flow",
    "current_step_index": 3,
    "total_steps": 5,
    "progress_percent": 40
  },
  "git": {
    "branch": "feature/auth",
    "last_commit": "abc123f",
    "last_commit_message": "feat: Add OAuth config",
    "uncommitted_count": 3
  },
  "notes": "Stopped at callback URL issue - need to fix redirect"
}

docs/PLAN.md (strategic plan):

# Project Plan

**Goal**: Add user authentication with OAuth2
**Created**: 2025-12-13
**Last Updated**: 2025-12-13
**Status**: In Progress

## Context

Building OAuth2 authentication for the web app. Need to support Google
and GitHub providers initially, with ability to add more later.

## Approach

Using JWT tokens with refresh rotation. Chose this over session-based
auth for better scalability and API compatibility.

### Alternatives Considered
- **Session-based auth**: Simpler but doesn't scale well
- **Auth0/Clerk**: Good but adds external dependency

## Implementation Steps

### Completed
- [x] Step 1: Research OAuth providers [S]
  - Completed: 2025-12-12
  - Commit: `abc123` research: Compare OAuth providers

### In Progress
- [ ] Step 3: Implement OAuth flow [M]
  - Started: 2025-12-13
  - Notes: Working on callback URL handling

### Pending
- [ ] Step 4: Add token refresh [S]
- [ ] Step 5: Write integration tests [M]

## Decision Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 12-12 | Use JWT over sessions | Better API compatibility |
| 12-12 | Start with Google only | Largest user base |

## Open Questions

- Should we support "Remember me" functionality?
- How long should refresh tokens last?

---
*Plan saved by `/save` command. Last updated: 2025-12-13 10:30*

.claude/claude-progress.md (human-readable):

# Session Progress

**Saved**: 2025-12-13 10:30 AM
**Branch**: feature/auth

## Plan Context

**Goal**: Add user authentication with OAuth2
**Current Step**: Step 3 - Implement OAuth flow
**Progress**: 40% (2/5 steps)

## Tasks

- [x] Set up OAuth credentials
- [ ] Fix callback URL handling (in progress)
- [ ] Add token refresh logic

## Notes

> Stopped at callback URL issue - need to fix redirect

---
*Restore with: /sync*

Output Format

Session saved

| Category | Value |
|----------|-------|
| **Plan** | Step 3/5 (40%) - Implement OAuth flow |
| **Tasks** | 1 completed, 1 in progress, 1 pending |
| **Git** | 3 uncommitted files on feature/auth |
| **Notes** | "Stopped at callback URL issue..." |

Files written:
  .claude/session-cache.json
  .claude/claude-progress.md
  docs/PLAN.md

Restore with: /sync

Archive Mode: `/save --archive`

Archives current plan before saving fresh state.

What It Does

Moves docs/PLAN.md to docs/PLAN-<date>.md
Clears .claude/session-cache.json
Saves new state (if any)

Output

Archived: docs/PLAN.md -> docs/PLAN-2025-12-13.md

Session saved (fresh start)

Files written:
  docs/PLAN-2025-12-13.md (archived)
  .claude/session-cache.json (cleared)

Usage Examples

# Save current state
/save

# Save with notes
/save "Stopped at auth module, need to fix redirect"

# Archive current plan and start fresh
/save --archive

Status Markers

Marker	Meaning
[x]	Completed
[ ]	Pending/In Progress

Effort Indicators

Tag	Meaning
`[S]`	Small - Quick task
`[M]`	Medium - Moderate effort
`[L]`	Large - Significant effort

File Locations

File	Purpose	Git-tracked?
`docs/PLAN.md`	Strategic plan	Yes
`.claude/session-cache.json`	Session state	Optional
`.claude/claude-progress.md`	Human-readable progress	Optional
`docs/PLAN-<date>.md`	Archived plans	Yes

Integration

Command	Relationship
`/save`	This command - Persist state out
`/sync`	Complementary - Read state back in
Native `/plan`	Claude Code's planning mode (captured on save)

Notes

Non-destructive - Never overwrites without archiving option
Git-aware - Captures branch, commit, uncommitted changes
Human-readable - Progress files work without Claude Code
Ensure .claude/ directory exists (created if missing)

save.md 6.8 KB History Raw