Checkpoint

Save all session state and prepare for a clean handoff to the next session. Delegates heavy work to a subagent to keep parent context lean.

Steps

0. Persist unsaved findings (parent does this — NOT the subagent)

Before delegating, review the conversation for any research findings, evidence, analysis, or detailed information that was discussed but not yet written to a memory topic file. This is the #1 cause of data loss at checkpoint — the subagent cannot see conversation context, so anything not already in a file will be lost.

For each unsaved finding:

• Write it to an appropriate topic file in the project's memory directory (e.g.

  project_<topic>.md

  ,

  feedback_<topic>.md

  )
• Include the full detail — do NOT summarize or abbreviate
• Add a pointer in

  MEMORY.md

  if the topic file is new

If all findings are already persisted in topic files, skip this step.

1. Delegate save work to a subagent

Spawn a subagent (model: "sonnet") using the Task tool to perform all the heavy I/O. Pass it the following context:

• The project's memory file path (e.g.

  ~/.claude/projects/<project>/memory/MEMORY.md

  )
• What was accomplished this session (bullet list of concrete outcomes, not a vague summary)

• $ARGUMENTS

  if provided (use as next-steps summary)
• The current working directory

The subagent prompt should instruct it to:

1. Update memory: Read the project's

   MEMORY.md

   . Update the "Current Work" section with what was done, current state, and next steps. Replace the previous entry (do not accumulate). Add date stamp. Do NOT attempt to summarize research findings here — detailed findings belong in topic files (written in Step 0), not in MEMORY.md. Current Work should only contain status, outcomes, and next steps. Keep MEMORY.md under 80 lines (hard stop: 120) — it is an index of one-line pointers, not a knowledge base. Clear the

   ## Recovered from previous session

   section entirely if it exists — its content has been incorporated into Current Work.

2. Commit and push: Run

   git status

   . If there are uncommitted changes, stage relevant files (not build artifacts, logs, or secrets), commit with a descriptive message, and push to remote. If no changes or not a git repo, skip.

3. Sync knowledge repo (if applicable): If

   ~/.claude/knowledge

   exists and has a

   .git

   directory:

   if [ -f "$HOME/.claude/hooks/knowledge-db.js" ]; then
     node ~/.claude/hooks/knowledge-db.js export ~/.claude/knowledge/entries.jsonl 2>/dev/null
   fi
   bash ~/.claude/scripts/skills/sync-knowledge-repo.sh --knowledge-dir ~/.claude/knowledge
   

4. Verify: Run

   git status

   to confirm clean working tree.

5. Clear session state: Delete the session marker and loop detector to indicate a clean exit:

   # Derive the project dir from cwd — Claude Code encodes the path with slashes as dashes.
   PROJECT_SLUG=$(pwd | sed 's|/|-|g')
   PROJECT_DIR=$(echo "$HOME/.claude/projects/${PROJECT_SLUG}" | sed 's|//|/|g')
   # Fall back to most-recently-modified project dir if the derived path doesn't exist.
   if [ ! -d "$PROJECT_DIR" ]; then
     PROJECT_DIR=$(ls -dt ~/.claude/projects/*/ 2>/dev/null | head -1)
   fi
   rm -f "$PROJECT_DIR/session-marker.json"
   rm -f "$PROJECT_DIR/loop-detector.json"
   # Only delete session-specific state, not the entire shared recovery directory
   # (other concurrent sessions may be using it)
   if [ -n "${CLAUDE_LOOP_PID:-}" ] && [[ "${CLAUDE_LOOP_PID}" =~ ^[0-9]+$ ]]; then
     rm -f "/tmp/claude-subagent-recovery/recovery-${CLAUDE_LOOP_PID}.json"
   fi
   

6. Return a one-line summary of what was done (e.g. "Memory updated, committed abc1234, pushed to origin").

2. Exit decision

After the subagent returns, print exactly:

CHECKPOINT COMPLETE

Check if running under claude-loop:

echo "CLAUDE_LOOP=${CLAUDE_LOOP:-0} SENTINEL=${CLAUDE_LOOP_SENTINEL:-}"

If

CLAUDE_LOOP=1

(headless/task-queue mode): Write the sentinel and exit.

[[ "${CLAUDE_LOOP_PID}" =~ ^[0-9]+$ ]] || exit 0
SENTINEL="/tmp/claude-checkpoint-exit-${CLAUDE_LOOP_PID}"
echo '{"reason":"checkpoint","timestamp":'$(date +%s)'}' > "${SENTINEL}"

Print exactly "Exiting — claude-loop will respawn." Then STOP. Do not make any more tool calls or produce any more output.

If

CLAUDE_LOOP_SENTINEL

is set (interactive mode under claude-loop): Write the sentinel.

[[ "${CLAUDE_LOOP_PID}" =~ ^[0-9]+$ ]] || exit 0
SENTINEL="/tmp/claude-checkpoint-exit-${CLAUDE_LOOP_PID}"
echo '{"reason":"checkpoint","timestamp":'$(date +%s)'}' > "${SENTINEL}"

Print exactly:

Checkpoint complete. Session will restart with fresh context.

Then STOP. Do not make any more tool calls or produce any more output.

If neither is set (standalone session, no claude-loop): Print exactly:

Checkpoint complete. Exiting session.

Then STOP. Do not make any more tool calls or produce any more output. The session is over.