# Checkpointed Agent Loop

Run long or failure-prone Claude Code tasks as bounded, resumable loops with a durable...

- Repository: https://github.com/davepoon/buildwithclaude (3705 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add davepoon/buildwithclaude --skill checkpointed-agent-loop -g -a claude-code -y`
Codex: `npx skills add davepoon/buildwithclaude --skill checkpointed-agent-loop -g -a codex -y`
Cursor: `npx skills add davepoon/buildwithclaude --skill checkpointed-agent-loop -g -a cursor -y`
Gemini CLI: `npx skills add davepoon/buildwithclaude --skill checkpointed-agent-loop -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add davepoon/buildwithclaude`

## Description

Run long or failure-prone Claude Code tasks as bounded, resumable loops with a durable state machine, attempt budget, and verification evidence checkpoint.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```text
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:

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

The rest: https://github.com/davepoon/buildwithclaude/blob/HEAD/plugins/all-skills/skills/checkpointed-agent-loop/SKILL.md