checkpointed-agent-loop

Runs resumable Claude Code tasks as bounded loops with checkpointed state and verification evidence.

3.4k|487|Updated Jul 25, 2025
One-click install
npx skills add https://github.com/davepoon/buildwithclaude --skill checkpointed-agent-loop
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: checkpointed-agent-loop
Source: https://github.com/davepoon/buildwithclaude/tree/main/plugins/all-skills/skills/checkpointed-agent-loop
Command: npx skills add https://github.com/davepoon/buildwithclaude --skill checkpointed-agent-loop

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Long-running or failure-prone Claude Code tasks lose progress when a session is interrupted, forcing agents to reconstruct state from chat history and risking unbounded retries or unverified claims of success. This Skill persists task state in a local checkpoint file so work can resume from explicit state with a finite attempt budget and recorded verification evidence.

Core Features & Use Cases

  • Durable State Machine: Enforces a strict planned → running → verifying → succeeded/failed/blocked transition graph with terminal-state immutability and atomic file persistence.
  • Bounded Attempt Budget: Each entry into running consumes one attempt, and transitions are rejected once maxAttempts is exhausted, preventing infinite retry loops.
  • Verification Evidence Gate: A task cannot transition to succeeded until at least one passing evidence record is appended during the verifying state.
  • Use Case: An agent migrating a database table is interrupted mid-task; the next session runs the status command, reads the saved nextAction, performs only that bounded step, records the actual test result, and then marks the task succeeded or schedules a bounded retry.

Quick Start

Ask Claude Code to initialize a checkpointed loop for your task with a finite attempt budget, then let it transition through running and verifying states while recording test evidence before marking the task complete.

Frequently Asked Questions about checkpointed-agent-loop

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I resume an interrupted Claude Code task?

Run the checkpoint-loop status command on the checkpoint file to see the current state, attempt count, and saved nextAction. Continue from that nextAction instead of reconstructing progress from conversation history, and never repeat a completed attempt.

How do I add bounded retries to a long-running agent task?

Initialize a checkpoint with a finite max-attempts value, then transition through running and verifying for each attempt. Entering running consumes one attempt, and once the budget is exhausted further transitions into running are rejected with an attempt budget exhausted error.

Does the checkpoint script execute tests or shell commands?

No, the helper only stores state and evidence records. It never executes commands, calls a model, spawns agents, or accesses the network; Claude Code runs the actual checks with normal tool policy and records the observed outcome.

Why is a transition to succeeded rejected in the checkpoint loop?

A transition to succeeded requires at least one passing evidence record appended while in the verifying state. Record the real check result with the evidence command first; failed outcomes cannot be rewritten into passing records.

When should I not use a checkpointed agent loop?

Avoid it for one-line edits or workflows that already have their own durable runner. It is designed for tasks that span sessions, need bounded retries, or must prove verification before being called complete.