# Checkpoint

> Write a timestamped, secret-redacted snapshot of decisions, progress and next actions to the checkpoints directory, then link it from the active session log. Use when you say `checkpoint this`, `save a recovery point`, or `snapshot where we are` before a risky change or at the end of a working block. Do NOT use to commit or push (it never does either), and do NOT use to write a retrospective (use retro).

- Skill: `rjmurillo/checkpoint` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rjmurillo/checkpoint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rjmurillo/checkpoint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- License: MIT
- Author: rjmurillo (https://skillmd.com/u/rjmurillo)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/rjmurillo/checkpoint

---


# Checkpoint

<!-- vendor-portability: the redactor this skill pipes every checkpoint body
     through is scripts/redact_secrets.py, which lives upstream in the
     rjmurillo/ai-agents repo and ships in no plugin root. The checkpoint and
     session directories it reads and writes are the CONSUMER's own agent
     artifacts, resolved rather than hard-coded (ADR-083, issue #5632). -->

<!-- vendor-portability-exec: the redaction step invokes
     scripts/redact_secrets.py, which lives upstream in the rjmurillo/ai-agents
     repo. A prose declaration does not exempt an executable invocation, which
     migrates independently (issue #2838), so it is declared here too. -->

Migrated from the checkpoint command under ADR-064, which makes skills the
single user-invocable surface. The command file is gone, so its path is named
here in plain text rather than as a citation to something a reader could open.

@CLAUDE.md

## The checkpoint and session directories

Resolve them the way `paths.artifact_dir` does, then take its `checkpoints/` and
`sessions/` subdirectories. Do not hard-code an agent-artifacts path: the tree
this skill writes into lives in the CONSUMER's workspace, and its root differs
between an upstream checkout and a plugin install. Every `{checkpoints-dir}` and
`{sessions-dir}` below means those resolved directories.

Capture the current state of work as a durable, timestamped snapshot. Use this
mid-session when you want a recoverable save point before a risky change, at the
end of a working block, or whenever the user asks to "checkpoint" progress. The
file is the human-readable record; the session log keeps a reference to it.

## Triggers

| Trigger | Effect |
| --- | --- |
| `/checkpoint` | Write a timestamped checkpoint and link it from the active session log. |
| `/checkpoint label` | Write a labeled checkpoint and link it from the active session log. |

## Arguments

Optional label for this checkpoint: $ARGUMENTS

## Process

### Phase 1: Build checkpoint path

Resolve the timestamp, active session log, label, slug, and collision-safe
checkpoint path.

### Phase 2: Build and redact checkpoint

Render the checkpoint body and run it through the secret redactor before any
Write call.

### Phase 3: Persist and link

Write the redacted checkpoint to a path that does not already exist. Append
checkpoint metadata to the active JSON session log when one exists, then validate
the JSON.

## Steps

The three phases expand into eight steps: resolve the timestamp and branch, find
the active session log, build the path, render the body, redact it, write it to a
path that does not exist, link and validate the session log, then report. Each
step, with its exact commands and failure handling, is in
`references/steps.md`. Read it before writing anything; the redaction and
validate-before-edit ordering is the part that matters.

## Verification

- [ ] Checkpoint file path did not already exist before Write.
- [ ] Checkpoint body was redacted with `scripts/redact_secrets.py` before Write.
- [ ] Active session log was updated, or the "no active session log" reason was reported.
- [ ] Updated session log JSON was validated before editing the original file.
- [ ] Updated session log passed `python3 -m json.tool` when a log was modified.

## Anti-Patterns

- Do not overwrite an existing checkpoint path.
- Do not write unredacted durable text when the redactor fails.
- Do not create or guess a session log when no active branch-matching log exists.
- Do not edit a session log before validating the complete updated JSON string.
- Do not commit, push, or merge from this command.

## Extension Points

- Add a restore command separately. Checkpoint only writes and links snapshots.
- Add automatic checkpointing separately. This command stays human-triggered.

This command writes a snapshot file and records a reference in the active session
log when one exists. It does not push or commit. Keep it to the steps above.