Skip to content

Checkpoints

Before every agent turn, CodeBuddy snapshots the affected files. If you don’t like where the turn went, revert atomically. Captures on-disk content, not just editor buffers — files you haven’t opened are protected too.

Two things are called “checkpoints.” This page covers the file-snapshot CheckpointService — the multi-file undo below. Separately, the agent loop persists conversation state to a LangGraph SQLite checkpointer for durable resume across reloads; that system is per-session isolated (thread_id == sessionId) and pruned (soft cap ~32 checkpoints/thread, keeping the last few per turn) after a bug where it grew to ~1.2 GB and OOM’d. You don’t interact with the conversation checkpointer directly — it’s what makes a reloaded session pick up where it left off.

Flow

Section titled “Flow”
graph TB A[Agent turn starts] --> B[CheckpointService.createCheckpoint<br/>Snapshots all tracked + extra files] B --> C[Agent executes<br/>Edits / creates / deletes files] C --> D[User reviews] D -->|Happy| E[Continue] D -->|Revert| F[revertToCheckpoint id<br/>Restore every file to snapshot state<br/>Delete files that didn't exist yet] F --> G[Checkpoints after this point discarded]

Before writing any file, the agent calls trackFile() to register the path. createCheckpoint() reads every tracked file from disk and stores it in memory. Files that don’t exist yet are recorded with didNotExist: true — reverting deletes them.

Snapshot shape

Section titled “Snapshot shape”
FieldMeaning
idUnique ID (ckpt-{timestamp}-{random})
labelHuman-readable label (e.g. “Before turn 3”)
timestampUnix timestamp of creation
conversationIdThread ID the checkpoint belongs to
filesFile snapshots — path, content, existence flag

Reverting

Section titled “Reverting”

When you revert:

  1. Files that existed at checkpoint time → content restored.
  2. Files that didn’t exist at checkpoint time → deleted (the agent created them).
  3. All checkpoints created after the target → discarded (no redo across a revert).
  4. Parent directories re-created as needed if a restored file’s parent was deleted.

Limits

Section titled “Limits”
  • 50 checkpoints per session. Cap reached → oldest evicted.
  • In-memory only. Don’t survive editor restarts — keeps the feature lightweight, avoids disk bloat.
  • Agent-touched files only. Your own manual edits outside the agent flow aren’t captured.

Reverting from the UI

Section titled “Reverting from the UI”

Restore a checkpoint from the chat panel — pick the turn you want to roll back to. (There is no Revert to Checkpoint palette command; reverting is UI-driven.)

vs. editor undo

Section titled “vs. editor undo”

Checkpoints are separate from Cmd/Ctrl+Z. Use editor undo for single-file undo of your own edits. Use checkpoints to revert multi-file agent changes atomically.

Section titled “Related”