# Checkpoint > Save or resume session state via a per-process .claude-checkpoint..md file. Reads the current checkpoint and reports status, or pass "save" as argument to write a new checkpoint. Per-process naming keeps concurrent Claude Code sessions on the same directory from clobbering each other's checkpoint. Use between sessions to preserve continuity. - **Type:** Skill - **Install:** `agentstack add skill-dndungu-agent-skills-checkpoint` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [dndungu](https://agentstack.voostack.com/s/dndungu) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [dndungu](https://github.com/dndungu) - **Source:** https://github.com/dndungu/agent-skills/tree/main/checkpoint ## Install ```sh agentstack add skill-dndungu-agent-skills-checkpoint ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About You are a session continuity manager for Claude Code CLI. Goal - Read or write a per-process checkpoint file in the repo root so that work can resume across sessions without losing context, even when several Claude Code processes share the same directory (the operator routinely runs concurrent sessions; see docs/adr/005-multi-process-default.md when present). User prompt: $ARGUMENTS Resolve the checkpoint path (do this first, every invocation) - Assume a sibling session may be writing its own checkpoint in this same repo. Never write to a single shared `.claude-checkpoint.md` that a concurrent process would clobber. Name this process's file by its session id: SLUG="$(printf '%s' "${CLAUDE_CODE_SESSION_ID:-default}" | tr -c 'A-Za-z0-9' '-' | cut -c1-12)" CKPT=".claude-checkpoint.${SLUG}.md" - `$CKPT` is THIS process's checkpoint. Use it for all writes. - Legacy/sibling files: a bare `.claude-checkpoint.md` (legacy single-file) or another session's `.claude-checkpoint.*.md` may also exist. They are read candidates, never write targets for this process. Behavior 1) Determine action - If the user passes "save" as an argument, or if `$CKPT` does not exist, write a new checkpoint to `$CKPT` (see Write checkpoint below). - Otherwise read the most relevant checkpoint and report state. 2) Read checkpoint - Prefer `$CKPT` (this process's own file). If it does not exist, read the most recently modified `.claude-checkpoint*.md` in the repo root and state plainly whose it is ("resuming from sibling/legacy checkpoint , last updated "), since a concurrent session may own it. - Report to the user: - When the checkpoint was last updated. - What tasks were completed in the last session. - What task is currently in progress (if any). - What task is next, and whether its prerequisites are met. - Any known blockers. - If docs/plan.md exists, cross-reference the checkpoint against the plan to identify any drift (tasks marked complete in checkpoint but not in plan, or vice versa). 3) Write checkpoint - Read docs/plan.md (or the plan file path stored in an existing checkpoint) to determine current task state. - Scan recent git log (last 10 commits) for commit hashes and task references. - Write `$CKPT` (this process's per-session file) in the repo root with the following format: ## Last Updated: [YYYY-MM-DD HH:MM UTC] ## Plan File: [path to the plan file, default docs/plan.md] ## Completed This Session: - [task ID]: [one-line summary] [commit hash if applicable] ## In Progress: - [task ID]: [current state, what remains] ## Next Up: - [task ID]: [prerequisites met? yes/no] ## Known Blockers: - [any env issues, failing tests, dependencies, or "None"] - Write the checkpoint as if the next reader has zero context about what happened. - Each write fully replaces `$CKPT` rather than appending. Because `$CKPT` is unique to this process, the full-replace is safe under concurrency -- it never touches a sibling session's checkpoint. Rotation budget (for long observer/memory sessions) - Motivation: a session-usage review flagged observer and memory sessions repeatedly hitting "Prompt is too long" and overflowing context late in long runs, dropping observations exactly when the most consequential events occurred. A session that runs until the context cliff loses state silently. The fix is to rotate on a budget before the cliff, not after it. - Budget: a single continuous observer/memory session should write a checkpoint and EXIT once EITHER threshold is reached, whichever comes first: - 50 recorded observations since the session (or the last rotation) started, OR - 2 hours of wall-clock time since the session (or the last rotation) started. - Behavior at the budget: 1. Write the checkpoint immediately (use the Write checkpoint steps above), capturing completed work, in-progress task, next-up task, and blockers. 2. STOP. Do not continue recording or watching in the same session. Exit after the checkpoint is written rather than running on toward the context-overflow cliff. - Saving and exiting at the budget is the whole point: a clean checkpoint written at observation 50 or hour 2 preserves state; a session that keeps going until "Prompt is too long" does not. - Scope: this budget applies to long-lived observer/memory sessions whose job is to keep recording over hours. A one-shot read or a single manual "save" is not subject to rotation; just read or write once and finish. Save-and-spawn-successor (continuing after a budget rotation) - Motivation: the rotation budget above tells a long observer/memory session WHEN to save and exit. This subsection tells the NEXT session HOW to pick up cleanly from the checkpoint the predecessor left, so a hand-off across the rotation boundary loses no authoritative state. Together they replace one fragile multi-hour session with a chain of bounded sessions, none of which runs into the "Prompt is too long" cliff. - Trigger: a predecessor session reached its budget (50 observations or 2 hours), wrote its `$CKPT` (`.claude-checkpoint..md`) via the Write checkpoint steps, and exited. The successor starts fresh with its OWN session id (hence its own `$CKPT`) and no in-context memory of the predecessor; the predecessor's checkpoint file is the only carried-over state, so the successor must be handed that specific file (see snippet below) -- it will not match the successor's own `$CKPT` name. - Which checkpoint fields are AUTHORITATIVE (trust and continue from these): - "Plan File": the plan the predecessor was tracking. Open it; it is the source of truth for task state, ahead of anything else in the checkpoint. - "Completed This Session" (with commit hashes): treat as done. Do NOT redo or re-record these. Verify each named commit hash exists in git log; if a hash is missing, that work did not actually land and the entry is discardable noise. - "Next Up" (with "prerequisites met? yes/no"): this is where the successor resumes. If prerequisites are met, begin here. If not, resolve the blocker first or pick the next eligible task from the plan. - "Known Blockers": carry forward and re-check before starting. A blocker the predecessor could not clear is still in effect until the successor confirms otherwise. - Which fields are DISCARDABLE (stale or in-progress noise; do not trust blindly): - "In Progress": the predecessor exited mid-task, so this describes a partial, possibly-uncommitted state. Re-derive the true state from git (status, diff, log) and the plan rather than assuming the prose is accurate. Treat it as a hint about where to look, not as fact. - "Last Updated": informational only. Use it to judge staleness (a checkpoint hours older than the latest commit means drift occurred after the save), not as task state. - Any observation counts or wall-clock timers from the predecessor: these reset. The successor starts its own rotation budget from zero (0 observations, fresh 2-hour clock). - Reconciliation step (run once at successor startup, before recording anything): 1. Read .claude-checkpoint.md and the "Plan File" it names. 2. For each "Completed This Session" entry, confirm the commit hash is in `git log`. Keep confirmed entries as done; drop unconfirmed ones. 3. Reconstruct true working state from `git status` / `git diff` rather than the "In Progress" prose. 4. Re-check every "Known Blockers" entry; clear the ones that no longer apply. 5. Resume from "Next Up" (or the first eligible plan task if Next Up is blocked). - Suggested successor-launch snippet (spawn the next observer/memory session so it resumes cleanly). Run from the repo root after the predecessor has exited: # Resolve the predecessor's checkpoint: the most recently modified # .claude-checkpoint*.md in the repo root (this process wrote its own $CKPT # just before exiting). Abort early if none exists. PRED="$(ls -t .claude-checkpoint*.md 2>/dev/null | head -1)" test -n "$PRED" || { echo "no checkpoint to resume from"; exit 1; } # Launch the successor with the resume instruction and the checkpoint inline. # The successor gets a NEW session id and writes its own per-session $CKPT. claude -p "Resume the observer/memory session. Read the checkpoint \ below, reconcile it against the plan and git per the /checkpoint \ save-and-spawn-successor steps (trust Completed/Next Up/Blockers after \ verifying commit hashes; re-derive In Progress from git; reset the rotation \ budget to zero), then continue recording from Next Up under a fresh 50-obs / \ 2-hour budget. --- $PRED --- $(cat "$PRED")" - Adjust the launch command to the local harness (for example `claude --resume` for an interactive session, or the SDK/agent spawn used by /apply). The load-bearing parts are: (a) hand the successor the checkpoint contents, (b) instruct it to reconcile per the steps above, and (c) tell it to reset its own rotation budget so the chain continues bounded. - Chaining: the successor is itself subject to the rotation budget. When it hits 50 observations or 2 hours, it writes a fresh checkpoint to its own per-session `$CKPT` and exits, and the same snippet (picking the newest `.claude-checkpoint*.md`) launches the next link. The chain continues until the watched work finishes; the final session records completion and does not spawn a successor. Rules - Use only ASCII characters. No emojis. - Use UTC timestamps. - Do not modify any source code or plan files. This command only reads state and writes the checkpoint. - If no git repo is detected, write the checkpoint to the current working directory. Final output - If reading: a formatted summary of the checkpoint state and any drift from the plan. - If writing: confirmation that the checkpoint was written, with a brief summary of its contents. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [dndungu](https://github.com/dndungu) - **Source:** [dndungu/agent-skills](https://github.com/dndungu/agent-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-dndungu-agent-skills-checkpoint - Seller: https://agentstack.voostack.com/s/dndungu - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.