checkpoint

Overview

Unified state capture that saves everything needed to resume work exactly where you left off. Combines git state, task progress, and session decisions into a single checkpoint.

How this differs from other skills:

• /task-persist — saves task list only. This skill saves full working context (git + tasks + decisions).
• /session-wrap — captures session summary for handoff. This skill saves restorable state, not just a narrative.
• /strategic-compact — manages context window. This skill manages cross-session state.

Mode Detection

/checkpoint save            → save checkpoint with auto-generated name
/checkpoint save billing    → save checkpoint named "billing"
/checkpoint restore         → restore most recent checkpoint
/checkpoint restore billing → restore checkpoint named "billing"
/checkpoint list            → list all saved checkpoints

Save Mode

Step 1: Capture Git State

BRANCH=$(git branch --show-current)
COMMIT=$(git rev-parse --short HEAD)
STATUS=$(git status --porcelain)
STASH_NEEDED=$([ -n "$STATUS" ] && echo "true" || echo "false")

If there are uncommitted changes:

git stash push -m "checkpoint: ${NAME:-auto}-$(date +%s)"
STASH_REF=$(git stash list | head -1 | cut -d: -f1)

Step 2: Capture Task State

# From task-state.json if it exists
TASK_STATE=""
if [ -f ".context/task-state.json" ]; then
  TASK_STATE=$(cat .context/task-state.json)
fi

Step 3: Capture Decisions

# Recent decisions from memory
DECISIONS=""
if [ -f ".claude/memory/decisions.jsonl" ]; then
  DECISIONS=$(tail -20 .claude/memory/decisions.jsonl)
fi

Step 4: Capture Remaining Work

Summarize what's left to do based on:

• Open tasks in task state
• Uncommitted changes context
• Current branch purpose (from branch name)

Step 5: Write Checkpoint

CHECKPOINT_DIR="${CLAUDE_PLUGIN_DATA:-${HOME}/.pixl/plugin-data}/checkpoints"
mkdir -p "$CHECKPOINT_DIR"

NAME="${1:-$(date +%Y%m%d-%H%M%S)}"

cat > "$CHECKPOINT_DIR/${NAME}.json" <<EOF
{
  "name": "${NAME}",
  "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "git": {
    "branch": "${BRANCH}",
    "commit": "${COMMIT}",
    "stash_ref": "${STASH_REF:-null}",
    "has_uncommitted": ${STASH_NEEDED}
  },
  "tasks": ${TASK_STATE:-null},
  "decisions": [${DECISIONS}],
  "remaining_work": "<summarized by Claude>",
  "project_dir": "$(pwd)"
}
EOF