checkpoint

Checkpoint Command

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.

Optional label for this checkpoint: the problem statement from the conversation (under Copilot CLI the skill tool takes no argument vector, so state it in your message)

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.

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

1. Get the current UTC timestamp for the filename and the file body:

   date -u +%Y%m%d-%H%M%S
   

   Use the output as YYYYMMDD-HHMMSS. Also record the full ISO 8601 UTC time (date -u +%Y-%m-%dT%H:%M:%SZ) for the body.

2. Identify the active session log and default label:

   • Get the current branch with git branch --show-current.
   • Find .agents/sessions/*.json files and sort by filename descending. The filename order is the canonical "newest" order because session logs are named with YYYY-MM-DD-session-NN.
   • Read candidates in that order until you find the first log whose normalized session.branch equals the current branch. Normalize session.branch by trimming whitespace and removing one matching pair of surrounding backticks. That file is the active session log.
   • If $ARGUMENTS is empty after trimming, derive the label from the active session log's session.objective. If no active session log exists, derive it from the current branch. If that is empty, use checkpoint.