What happened between the goal and “done”

Coding work doesn’t always fit inside one conversation. The agent makes a decision, changes a few files, runs a check, and then the session runs out of room or I switch to something else. The code survives, but the next session has to reconstruct why we made that decision and what still needs work.

I built Agent Checkpoint to save that context under a task name: the goal, decisions, blockers, next action, and links to the actual work. It started in my dotfiles. We’ve now pulled it into a public repository so you can use it without adopting the rest of my setup.

The handoff solved the immediate problem, but as work moved between sessions I also wanted to review how it had progressed.

A checkpoint is a place to start

A fresh session should be able to find the design, understand the decision to keep the grammar small, and see that empty input still needs a test. That gives it a concrete next action, while the full design and code stay in the project where they belong.

Finishing needs more than a good summary. The CLI can run a verification command and record its exit code, so a failed check leaves the task open and a successful check can complete it. Manual overrides are explicit. I can distinguish the check that ran from an agent saying it checked something.

  1. SaveRecord the goal, decisions, blockers and next action.
  2. ResumeRead the handoff and inspect the current files.
  3. VerifyRun a concrete check and keep its result.
  4. ReviewLook back at how the task progressed across sessions.

The history is a feature

When I’m running several tasks, the latest checkpoint only tells me where each one ended up. I also want to see when the goal changed, which session picked it up, where verification failed, and what passed before the agent called it done.

Here’s a fictional workshop signup page moving through two sessions. The entries below illustrate recorded events; they are not output from a real project. Expand each stage to follow the work. Nothing here runs commands.

1. Session A starts the task
09:00 · Goal saved
Build a workshop signup page.
Decision: Keep the form on one page.
Next: Check keyboard navigation.
Agent: builder · Session: A

The first session leaves enough context to continue, including where the work is and what it still needs to verify.

2. The goal changes
09:12 · Goal changed
Build a workshop signup page with accessible error handling.
Decision: Focus the first invalid field after submission.
Agent: builder · Session: A

The current checkpoint carries the updated goal. The history preserves the earlier goal too, so I can review the change in scope instead of trying to remember what we originally asked for.

3. Session B takes over and the check fails
09:20 · Handoff recorded
From: builder / Session A
To: reviewer / Session B
Next: Check error focus and keyboard submission.

09:24 · Verification started
09:24 · Verification finished · Exit code: 1
Task status: Open

The failed attempt stays in the history. If another update makes a result stale while a check is running, the tool records the conflict rather than completing the newer work with that result.

4. The fix passes
09:31 · Verification started
09:31 · Verification finished · Exit code: 0
09:31 · Task completed
Outcome: Error focus and keyboard submission checked.
Agent: reviewer · Session: B

Now I can follow the recorded progression from the first goal through a scope change, a handoff, a failed check, and a successful one. The successful check supports a specific claim about the form. It doesn’t prove that every part of the page is correct.

Observability belongs in the tool

Once the history existed, I wanted to query it. history follows one task, timeline brings recorded events together, and stats summarizes things like verification results, handoffs and time spent blocked. Agent and session identities can be recorded explicitly, which lets me follow work as it moves between them.

This is the trajectory the tool records. It doesn’t capture every tool call or the model’s private reasoning, and it doesn’t guess what happened in an old session. When existing checkpoints are imported, they appear as labeled baseline snapshots. Earlier steps are unknown.

I also wanted the history to survive a broken latest-state file, so committed JSON event batches are the source of truth and the current checkpoint files can be rebuilt from them. There’s no SQLite database and no runtime package dependency. Python 3.11 or later is enough to run the tool on macOS or Linux, with Git for repository awareness.

For an existing observability setup, there’s optional OpenTelemetry export over HTTP: logs for recorded events and traces for verification attempts. The exporter uses the Python standard library. By default it omits task content and hashes identities; including content is an explicit choice. Export only happens when requested.

Use it in your own project

The repository has installation instructions, the CLI reference, and integration examples. From a checkout, the offline installer needs no pip or build dependencies:

python3 scripts/install.py

Once the command is on your path, start with one task and a check that means something for that project:

agent-checkpoint save --name signup \
  --goal "Build the signup page" --next "Run form checks"
agent-checkpoint complete signup --run "make test" \
  --note "Form checks passed"
agent-checkpoint history signup --json

Use your actual verification command in place of make test. The standalone installer installs the CLI; connecting session hooks is a separate integration step described in the repository.

I still want to spend my time defining the problem and making the important calls, then let the agent carry the work forward. A useful handoff helps it continue. A recorded history gives me something concrete to review when I come back.

Set this up with your own agent →

Next: giving an agent a useful health check →