/checkpoint - Save Progress

Save current work state as a thread to survive context loss.

Task ID (optional): $ARGUMENTS

Process

0. Capture session learnings Reflect on this session. If any reusable learnings exist (mistakes, patterns, gotchas, workflow improvements), call /learn for each before proceeding. Skip if nothing novel was learned. See CLAUDE.md ## Session Learnings for guidance.

0c. Extract session insights (lightweight) Same as /handoff step 0c but briefer — max 2 insights. Skip if session just started or no explanatory content generated. Call /learn with source: "session-insight" for each.

1. Check for recent auto-checkpoint (upgrade instead of duplicate)

   # Find auto-checkpoints from last 5 minutes
   find workspace/threads -name "T-*-auto-*.json" -mmin -5 2>/dev/null | sort -r | head -1
   

   If found: upgrade that file in-place (add full fields: initial_commit, commits_made, remote_url, knowledge_repos, worker, next_steps; change type to "checkpoint"; rename file to remove -auto-). Then continue from step 7 (INDEX updates).

2. Generate thread ID if not provided

   • Format: T-{YYYYMMDD}-{HHMMSS}-{slug}
   • Derive slug from recent work (e.g., mrr-report, email-fix)

3. Capture git state

   git rev-parse --abbrev-ref HEAD          # branch
   git remote get-url origin 2>/dev/null    # remote
   git rev-parse --short HEAD               # current commit
   git log --oneline -5                     # recent commits
   git diff --name-only HEAD~3              # recently touched files
   git status --porcelain                   # dirty check
   

4. Capture knowledge repo git states Knowledge folders may contain embedded git repos at their canonical real-directory paths. For any knowledge path in files_touched, capture its repo state. Continue detecting legacy symlinks only so they can be reported for migration:

   # For each knowledge repo with changes:
   bash -c '
   shopt -s nullglob
   for knowledge_path in core/knowledge/public/* core/knowledge/private/* personal/knowledge/* companies/*/knowledge; do
     if [ -L "$knowledge_path" ]; then
       target=$(cd "$knowledge_path" 2>/dev/null && pwd -P) || continue
       case "$target" in
         "$(pwd -P)"/core/packages/*) continue ;;  # package-managed mount — the only valid knowledge link
       esac
       repo_dir=$(cd "$knowledge_path" && git rev-parse --show-toplevel 2>/dev/null) || repo_dir=""
       hq_repo=$(git rev-parse --show-toplevel 2>/dev/null) || hq_repo=""
       if [ -n "$repo_dir" ] && [ "$repo_dir" != "$hq_repo" ]; then
         echo "$knowledge_path: INVALID legacy symlink to $repo_dir (migration required — run hq reindex)"
       else
         echo "$knowledge_path: NONSTANDARD symlink to $target (knowledge must be a real directory)"
       fi
       continue
     fi
     [ -d "$knowledge_path/.git" ] || continue
     repo_dir=$(cd "$knowledge_path" && git rev-parse --show-toplevel 2>/dev/null) || continue
     dirty=$(cd "$repo_dir" && git status --porcelain)
     [ -z "$dirty" ] && continue
     echo "$knowledge_path: $(cd "$repo_dir" && git rev-parse --short HEAD) (dirty)"
   done
   '
   

   Include dirty knowledge repos in the thread JSON under git.knowledge_repos.

5. Gather session state

   • Summarize what was accomplished
   • List files touched
   • Identify next steps

5.5. Close active session journal (if any) Spec: core/knowledge/public/hq-core/journal-spec.md. If a journal was opened earlier in this session by /brainstorm, /deep-plan, /prd, or /plan, close it now:

.claude/skills/_shared/journal.sh close "{project_dir}" "{one-line synthesis, ≤120 chars}"

Pass the resolved project directory that owns this session's journal. Fail-soft: no-op if no owned active journal pointer exists. Use the same one-line summary you used for conversation_summary below.

6. Write thread to workspace/threads/{thread_id}.json (include knowledge_repos from step 3):

   {
     "thread_id": "T-20260123-143052-mrr-report",
     "version": 1,
     "created_at": "ISO8601",
     "updated_at": "ISO8601",
   
     "workspace_root": "~/",
     "cwd": "current/working/dir",
   
     "git": {
       "branch": "main",
       "remote_url": "git@github.com:...",
       "initial_commit": "abc1234",
       "current_commit": "def5678",
       "commits_made": ["hash: message"],
       "dirty": false,
       "knowledge_repos": {
         "knowledge-{company}": {"commit": "abc1234", "dirty": true},
         "knowledge-ralph": {"commit": "def5678", "dirty": false}
       }
     },
   
     "worker": {
       "id": "worker-id or null",
       "skill": "skill-name or null",
       "state": "completed"
     },
   
     "conversation_summary": "1-2 sentence summary",
     "files_touched": ["relative/paths"],
     "next_steps": ["remaining tasks"],
   
     "metadata": {
       "title": "Human-readable title",
       "tags": ["searchable", "tags"]
     }
   }
   

7. Also write legacy checkpoint to workspace/checkpoints/{task-id}.json for backward compat

8. Update INDEX files and recent threads

   • Update workspace/threads/recent.md with last 15 threads (table format)
   • Update INDEX.md timestamp only (do NOT regenerate full content — it's now slim)
   • Regenerate workspace/threads/INDEX.md (all threads, full table)
   • Check files_touched for any companies/*/knowledge/ paths — if found, regenerate that company's knowledge/INDEX.md
   • See core/knowledge/public/hq-core/index-md-spec.md for INDEX format

8b. Document release Run /document-release — the skill resolves company + project context on its own. Best-effort — skip silently on failure.

9. Report

   Thread saved: workspace/threads/{thread_id}.json
   
   Summary: {summary}
   Git: {branch} @ {commit} ({dirty ? "dirty" : "clean"})
   Files: {count} files touched
   Next: {next_steps or "Work complete"}
   
   To hand off to fresh session: /handoff
   

Thread vs Checkpoint

Feature	Thread (new)	Checkpoint (legacy)
Git context	Full (branch, commits, dirty)	Minimal
Worker state	Captured	Not captured
Location	workspace/threads/	workspace/checkpoints/
Format	Rich JSON	Simple JSON

Notes

• Threads ensure work survives context clears
• Run frequently during long sessions
• If session feels long, suggest /handoff
• Threads are searchable via /search

See also

• /handoff — a full continuation package
• /journal — durable working memory