Checkpointing

Agents that edit files and run commands will occasionally take a wrong turn. Checkpointing gives you a safety net: the Syntic Agent SDK can snapshot both the agent’s conversational state and the contents of the workspace, then restore that snapshot later. If a run produces changes you don’t want, you roll back to a known-good point instead of untangling the diff by hand.

Creating checkpoints

You can let the SDK create checkpoints automatically at each turn, or create them explicitly at moments that matter to you — before a risky refactor, after a milestone, or on a schedule. Each checkpoint captures the session transcript plus a snapshot of tracked files.

import { query } from "@syntic/agent-sdk";
 
const session = query({
  prompt: "Migrate the database layer to the new ORM.",
  options: { checkpointing: { enabled: true, auto: true } },
});
 
for await (const message of session) {
  if (message.type === "checkpoint") {
    console.log("Saved checkpoint", message.checkpointId);
  }
}

Restoring and rolling back

Restoring returns the workspace and the agent to the captured state. This is the operation you reach for when a change went wrong: rewind to the checkpoint taken before the change, and both the files and the agent’s memory of the conversation are reset together, so the next turn starts from a coherent point.

from syntic_agent_sdk import query, restore_checkpoint
 
# Roll the workspace and session back to an earlier snapshot.
await restore_checkpoint(session_id="sess_123", checkpoint_id="ckpt_5")

When to use it

Checkpointing shines in autonomous and long-running scenarios where no human is watching every edit. Pair it with permissions and hooks: permissions prevent the clearly forbidden, hooks catch the questionable, and checkpoints let you recover from the merely mistaken. In interactive tools, expose checkpoints as an “undo” affordance so users can experiment freely, knowing every change is reversible.