Open Source•Apache-2.0 License

badgr-agent-resume

Step-level checkpointing for agent runs — resume from the last completed step instead of restarting from scratch after a crash.

npm install badgr-agent-resumeGitHub →

How it works

Multi-step agents crash mid-run and restart from scratch. A 20-minute agent that fails at step 8 of 10 wastes 18 minutes of compute and re-runs side effects. badgr-agent-resume wraps each step with a checkpoint so a crashed run picks up exactly where it left off.

1

Checkpoint each step

run.step(name, fn) checks .badgr/runs/ for an existing run; if the step already completed, it returns the saved output without re-running fn.

2

Resume after a crash

If the process crashes mid-run, re-running the script skips completed steps and resumes exactly at the failed one.

3

Inspect saved runs

Use run.timeline() in code, or the badgr-agent-resume resume CLI command, to see step status and durations for any saved run.

1

Install

Terminal
npm install badgr-agent-resume

Requires Node.js 18+ and TypeScript 5+ for type definitions.

2

Usage

Wrap an async workflow in agentRun() and checkpoint each step by name.

index.ts
import { agentRun } from "badgr-agent-resume";

await agentRun("support-agent", async (run) => {
  const plan  = await run.step("create-plan",   generatePlan);
  const order = await run.step("fetch-order",   () => fetchOrder(plan.id));
  return      await run.step("write-response", () => generateReply(order));
});
// Checkpoints saved to: .badgr/runs/support-agent-<timestamp>.json

Example output

run.timeline()
create-plan    completed  1.2s
fetch-order    completed  0.4s
write-response running    ...

Commands

badgr-agent-resume resume <run-id>Show the status of a saved run and resume instructions.
badgr-agent-resume resume <run-id> --jsonSame as resume, with machine-readable JSON output.
badgr-agent-resume connectShow an optional hosted run-history link.

What's included

✓Step-level checkpointing via run.step(name, fn) inside agentRun()
✓Automatic resume — completed steps are skipped on rerun after a crash
✓Checkpoints persisted locally to .badgr/runs/ (configurable via stateDir)
✓run.timeline() and formatTimeline() for human-readable step logs
✓loadRun() to inspect any saved run by ID
✓CLI: badgr-agent-resume resume <run-id> for status and JSON output
✓Typed AgentRunState / RecordedStep for programmatic inspection
✓Free, no signup required
View on GitHub →

Ready to try badgr-agent-resume?

npm install badgr-agent-resume — no account needed to get started.

Install from npmGet cloud API key