Picking up where an agent left off
I want to resume the work without reconstructing the whole conversation.
An agent can make progress for a while, then lose the context that explains why it made a decision. A fresh session might see the files but miss the unresolved question, or run a check that was already made obsolete by a later edit. I built a checkpoint CLI to give the next session a concrete place to start.
A checkpoint records the goal, the decisions, the next action, and the verification work. It points to the actual artifacts. The design document still lives with the project, because a short handoff should help me find the work rather than become another copy of it.
- SaveGoal, decisions, next action and artifact references
- ResumeRead the handoff and inspect the current files
- VerifyRun a concrete check and record the result
- FinishComplete after successful verification, or explicitly record a manual override
Explore a handoff
This fictional task is a workshop signup page. Expand each stage to see what the next agent gets. These examples run no commands.
1. The first session saves its place
Goal: Build the workshop signup page. Decision: Keep the form on one page. Artifact: The signup page and its design notes. Next action: Check keyboard navigation after the latest edit. Verification: Run the form interaction checks. Status: Open.
The next action is specific enough to start work. “Keep improving the page” would leave the next session guessing about what was unfinished.
2. A new session resumes the task
The agent reads the checkpoint, opens the referenced files, and checks their current state. It learns why the form stays on one page and that keyboard behavior still needs verification.
The handoff is context, not proof that the files are unchanged. The new session still has to inspect them.
3. Verification fails
Check: Form interaction checks Exit code: 1 Finding: Submitting an empty form does not focus the error. Checkpoint status: Open.
The agent can fix the focus behavior and run the check again. A failed completion check is recorded, but it does not turn the task into completed work.
4. The fix passes its check
Check: Form interaction checks Exit code: 0 Outcome: Error focus and keyboard submission checked. Checkpoint status: Complete.
The completion record keeps a short outcome and links to the artifact, so the work log can explain what finished. This check supports a specific claim about the form; it does not establish that every aspect of the page is correct.
Why this is a tool
I could ask the agent to write a paragraph before stopping, but then completion would just be another sentence it wrote. The CLI runs the verification command and records its exit code. The agent supplies context; the program enforces that completion requires either a successful check or an explicit manual override.
What I use in the real workflow
agent-checkpoint save creates or updates a named handoff. resume renders it for the next session. verify --run records a check while keeping the task open, and complete --run runs verification before completing it. A manual override is available when command verification does not fit, and it must be explicit.
I reuse a checkpoint name while a task continues. When work is abandoned or replaced, I close or supersede the old checkpoint so it stops looking like unfinished work I still intend to do.