Docs › Agent
Checkpoints and undo
Every way back: undoing one run, and restoring the whole workspace to an earlier point.
There are two ways back, at different granularities.
Undoing a run
Every run that changed files ends with a summary card, and its Undo puts back what that run changed: the files it edited, and what its commands generated, deleted or rewrote. A file that has changed again since the run, by you or by a later run, is left alone and named on the card. A run that only ran commands gets a card too, listing the files they changed. Undo still works after the window reloads. It is the right tool when a run did one thing and that thing was wrong.
Checkpoints
A checkpoint is a snapshot of the whole workspace, taken before each turn and before each edit or command the agent makes. Once a run spans dozens of edits and a few shell commands, per-run undo is the wrong granularity: you want to go back to a specific moment, not to the beginning.
Restoring takes a checkpoint of where you are first, so a restore can itself be undone: the confirmation that follows it has Undo restore. A restore that cannot write a file changes nothing, and one that fails part-way puts everything back as it was.
Checkpoints live in a separate repository outside your project, driven with their own git directory. This is the important part: committing into your repository would move your HEAD, rewrite your index and drop your staged changes. An editor feature that silently unstages a careful git add -p session is worse than no feature. Nothing about checkpoints touches your .git/.
Because they are outside your repository, checkpoints survive a branch switch and never appear in your diffs, and your own commits, branches and stashes are untouched by them.
What a restore does not bring back
A restore puts tracked files back. Things the agent created that were never snapshotted (build output, files matching your ignore rules) are left alone, so restoring does not wipe a node_modules or a .env you would have to rebuild. The exception is a file the agent edits with its own tools: that is snapshotted first even when it is ignored, so a .env the agent changed comes back.
The CLI keeps checkpoints the same way, in its own store: astracode-agent undo takes back the last run in a folder.
All documentation
Get started
Agent
- Agent overview
- Approvals and permissions
- Plan mode
- What the agent can do
- Running commands
- Browser tools
- Checkpoints and undo
- Infrastructure as code
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions