Guide 34 of 61 · Investigating and recovering
Undo what an agent changed
Preview what rolling back an agent's task would restore and keep, then apply the rollback from the checkpoint taken before the agent started.
Steps marked preview rely on a package that has not passed its release gate.
Find the task whose changes you want undone, preview what rolling it back would restore and what it would keep, bring back a file you edited since the agent did if you mean to, see why a file under a legal hold stays as it is, and apply the rollback from the checkpoint taken before the agent started.
1. Find the task
previewagentgarm run checkpoints the workspace after it registers the task and before the agent starts. The Claude Code pack asks for the git checkpoint (checkpoint: per_task): every tracked file and every untracked, non-ignored file up to 10 MiB, as on disk. Each checkpoint is normally kept in its own store, named by its task id, outside your repository; on a Linux install it is under ~/.local/state/agentgarm/checkpoints/git/, on macOS under ~/Library/Application Support/AgentGarm/checkpoints/git/.
Each store holds a workspace file naming the repository's git directory, so you can tell which repository a task worked in. While the agent still runs, agentgarm status --json lists each live task with its full task_id; agentgarm status shows only its last twelve characters.
ls -t ~/.local/state/agentgarm/checkpoints/gitcat ~/.local/state/agentgarm/checkpoints/git/<task>/workspacels -t ~/Library/Application\ Support/AgentGarm/checkpoints/gitagentgarm status --jsonChecked by the walk: this command ran as written on a no-root Linux install.
See also
Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last.
2. Preview the rollback, then apply it
Stop the agent first: agentgarm rollback refuses a task, or a task of its tree, that is still running. Run it as yourself, never with sudo and never from inside a governed task; both are refused. It prints the plan, starting Rollback in <work tree> (tier: git), with one line per file: restore, remove (a file that did not exist at the checkpoint), or keep with the reason, and how many files the agent changed already match the checkpoint. A plan with nothing to do says nothing to restore and exits 0.
In a terminal it asks Apply? [y/N]; anywhere else it prints the plan and Not applied: re-run with --yes to apply. and exits 1. Once applied it says Restored N file(s). and records the rollback with agentgarmd. Each file is checked again just before it is written, and one that changed after the plan was shown is kept and named.
After a kill, or a kill order from Central Lite preview, the same applies: nothing is checkpointed at kill time, so rollback restores the checkpoint taken at launch, once the task has ended (a suspended task still counts as running). No order rolls back for you. A hooks-only session, one not started with agentgarm run or agentgarm wrap, has no checkpoint, so it has nothing to roll back to (Find out why your agent stopped).
agentgarm rollback <task>agentgarm rollback <task> --yes3. Read what it restores and what it keeps
Rollback restores only files recorded as changed by the agent that still hold what was recorded. A file with no record is not touched, so your work elsewhere in the tree survives. The records come from the agent's own processes, so a forged one could name a file the agent never wrote: the preview lists every path, so check it before you confirm. A file you (or another process) changed after the agent's last write is kept as changed since the agent's last write. Also kept: ignored and untracked files the checkpoint did not capture, anything inside .git or outside the work tree, and agent configuration the sandbox never lets an agent write (such as .mcp.json or .claude/settings.json), which you restore by hand.
With the git checkpoint, the record of what the agent changed comes from its file-writing tool calls (Claude Code's Write, Edit, MultiEdit and NotebookEdit; Codex's apply_patch). A file the agent changed through a shell command is not recorded, so rollback does not list it, unless the macOS Endpoint Security sentinel preview is active, which records every file the task's processes write. And an edit of yours made between the checkpoint and the agent's write to the same file counts as “before”, so it is undone with the agent's change: check the preview before you confirm.
4. Restore a file you changed since
When you do want the checkpoint's version of a file listed as changed since the agent's last write, or as the agent's result was not recorded, name it with --include, once per file. The path is relative to where you run the command and must lie inside the work tree. The preview marks it (included although …). --include never lifts a legal hold or the protection of agent configuration.
agentgarm rollback <task> --include src/main.rs5. Leave files under a legal hold
A legal hold, placed with agentgarmd legal-hold place for all records, one task or one user, suspends rollback for what it covers: such a file is kept as under an active legal hold, and a rollback that restored nothing because of holds is recorded as a refusal. agentgarmd legal-hold list shows the holds. On a root install only root places, lists and releases them; a no-root install keeps them in your own store (agentgarmd legal-hold list --user), which any unsandboxed process of yours can edit.
6. Restore held files with your presence
preview--force-held restores held files too, only with a presence approval agentgarmd verifies. After you confirm the plan, it asks for one challenge naming exactly the held paths, which you confirm in agentgarm presence watch within 30 seconds. Without one (no key enrolled, a declined or lapsed challenge, or a no-root install) nothing is restored, the refusal is recorded and the command exits 2. A hold placed through Central Lite cannot be forced this way at all.
agentgarm presence watchagentgarm rollback <task> --force-heldSee also
Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only.
7. Roll back a workspace outside git
previewThe git checkpoint needs a git work tree. Outside one, agentgarm run says on stderr that the workspace is not in a git work tree and launches without a checkpoint, and agentgarm rollback refuses the task. A policy may instead ask for checkpoint: apfs (copy-on-write clones on macOS), overlay (OverlayFS on Linux, which needs a root install) or auto, which picks the best of these for the platform and falls back to git; the preview then names that tier, and restores and keeps files by the same rules, except that the overlay tier also lists what the agent changed through shell commands, and discards changes that never reached the workspace.