Checkpointed Agent Loop

Use this skill when a task can be interrupted, needs bounded retries, or must prove verification before it is called complete. It adds a small local checkpoint file around ordinary Claude Code work so a new context can resume from explicit state instead of reconstructing progress from chat.

The included Node.js utility stores state and evidence. It does not execute commands, call a model, spawn agents, access secrets, or contact a network service. Claude Code remains responsible for each actual tool call and for deciding whether a human approval is required.

When to Use This Skill

• A migration, refactor, test repair, or investigation may span multiple sessions.
• A bounded retry loop is safer than repeatedly improvising from conversation history.
• A task needs a durable next action and a record of which verification actually ran.
• You need to stop at an external dependency or a human decision without claiming success.

Do not use it for a one-line edit or a workflow that already has its own durable runner.

State Model

The checkpoint uses these states and only these transitions:

planned -> running
running -> verifying | failed | blocked
verifying -> succeeded | running | failed | blocked

succeeded, failed, and blocked are terminal. Entering running consumes one attempt, and the finite maxAttempts value cannot be exceeded. A transition to succeeded is rejected until the checkpoint contains at least one passing evidence record from verifying.

Setup

Choose a project-local path that is not committed with application code, for example .agent/checkpoints/data-migration.json. Keep objectives, reasons, and evidence free of API keys, tokens, passwords, personal data, and raw secret-bearing logs.

Set the helper path for the commands below:

SKILL_DIR="<absolute path to the installed checkpointed-agent-loop skill>"
CHECKPOINT=".agent/checkpoints/task.json"