---
title: "Rewind file changes with checkpointing Code Agent SDK"
source: https://docs.autohand.ai/agent-sdk/observability/checkpointing
---

# Rewind file changes with checkpointing

Every file the agent writes is tracked. The SDKs surface those writes as \`file\_modified\` events; the CLI records them on disk so you can review or revert later. This page covers both layers.

## How tracking works

Whenever the agent calls a write tool (\`write\_file\`, \`edit\_file\`, \`apply\_patch\`, or any custom MCP tool that reports a modification), the CLI emits a \`file\_modified\` event over JSON-RPC. The CLI also stores a record of the change under \`~/.autohand/runs/<run-id>/\` so the change can be inspected after the fact.

The SDK's job is to surface those events to your app; the CLI's job is to persist them.

## Observe file modifications in real time

Match \`file\_modified\` events while you stream a prompt. Use them to invalidate caches, refresh editor buffers, or track what the agent changed for an audit log.

## Revert with git

The simplest, safest revert path is git. Run inside a clean working tree (or commit before each agent run) so you can \`git restore\`, \`git stash\`, or \`git reset --hard\` if the agent goes off the rails.

If you let the agent commit on your behalf, restrict it to its own branch:

## Inspect run history with the CLI

The CLI keeps a per-run history under \`~/.autohand/runs/\`. Use it when you need to inspect what an agent did across multiple sessions, including ones that did not commit to git.

The exact subcommands depend on your CLI version. Run \`autohand runs --help\` to see what is available locally.

## Best practices

-   Run agents inside a clean git working tree so revert is one command away.
-   Stream \`file\_modified\` into your editor / IDE integration so users see changes the moment they happen.
-   For unattended runs, write \`file\_modified\` paths to an audit log alongside the run ID. That pair lets you tie back any change to the agent and prompt that produced it.
-   Do not rely on CLI run history for compliance. Treat it as a developer convenience; treat git (or your VCS of choice) as the source of truth.