kosa8

kosa8 / Guides

Guide · Checkpoint and rewind

How do I undo what an AI coding agent did?

Updated

Commit before the agent starts, then use git to inspect and roll back its edits to files in your repository. Git does not record packages the agent installed, files outside the repository, database contents or processes it started, so it cannot undo those. To undo everything, run the agent inside a machine you can checkpoint and rewind as a whole: a kosa8 sandbox saves its disk, memory and running processes, and a rewind takes about a second.

01Steps

  1. Commit before the agent starts. A clean commit is the point git can return to. git stash -u works too if you are not ready to commit.

    terminal
    git add -A && git commit -m "before agent run"

  2. See what the agent changed. git status lists modified and new files, git diff shows the edits, and git clean -nd lists untracked files without deleting anything.

    terminal
    git status
git diff
git clean -nd

  3. Roll back the repository. git restore . reverts tracked files, git clean -fd deletes the untracked files the dry run listed, and git reset --hard also drops any commits the agent made. If it rewrote history, git reflog still lists the commit you started from.

    terminal
    git restore .
git clean -fd
git reflog

  4. For everything git misses, install kosa8 (Apple silicon Mac or x86-64 Linux) and create a sandbox for the agent to work in.

    terminal
    curl -fsSL https://kosa8.com/install.sh | sh
kosa8 sandbox create web

  5. Take a checkpoint before the risky step. The label records why.

    terminal
    kosa8 checkpoint web --label "before migration"
checkpoint web-ckpt-1 (before migration) saved in 2281ms
  rewind with `kosa8 rewind web`

  6. Rewind when it goes wrong. The sandbox comes back under the same name, with its processes resumed.

    terminal
    kosa8 rewind web
Rewind web to web-ckpt-1 — before migration?
Everything since 2m ago will be lost. [y/N] y
web is back at web-ckpt-1 (1065ms)
  processes resumed from 2m ago

  7. Go further back if you need to. List the checkpoints, then rewind to one by label or id. -y skips the prompt in scripts; --json gives machine-readable output.

    terminal
    kosa8 checkpoint ls web
kosa8 rewind web -y --to "before migration"

An agent connected through kosa8's MCP server (kosa8 mcp serve) can do the same itself with the sandbox_checkpoint, sandbox_checkpoint_list and sandbox_rewind tools, so it can guard its own risky steps.

02What does git not undo after an AI agent runs?

Git only versions the files it tracks inside one repository. It does not undo packages the agent installed, changes to files outside the repository, writes to a database, or processes and containers the agent started.

  • Installed packages. npm install -g, pip install or brew install write outside the repository, and node_modules is usually in .gitignore.
  • Files outside the repository. Shell profiles, ~/.ssh, other projects and anything in your home directory are invisible to the repository's history.
  • Ignored files. .env files and build output are usually ignored, so git cannot restore them, and git clean -fdx deletes them.
  • Databases. A migration or a DELETE against a local database changes its data directory, not your source files.
  • Running processes. A server, a background job or a container the agent started keeps running after you reset the files.

03What does a whole-machine checkpoint restore?

A kosa8 checkpoint captures the sandbox exactly as it is: memory, running processes and disk. A rewind brings back that machine under the same name, still mid-task, so a database is still holding its connections and anything installed after the checkpoint is gone.

Each agent's sandbox is a microVM with its own kernel, so everything the agent installs, writes or starts lands on that machine and not on your computer. Because the sandbox keeps its name, scripts, agent configuration and shell history still point at the right thing after a rewind.

kosa8 keeps ten checkpoints per sandbox and drops the oldest past that, because each one costs a disk clone. Rewinding to an earlier checkpoint drops the ones taken after it.

04What can a rewind not undo?

A rewind restores the sandbox, not the outside world. It cannot unsend a request, an email or a git push the agent already made, and it cannot itself be undone, so take a checkpoint first if you might want the current state back.

  • Shared host folders. A folder shared in with kosa8 sandbox create --mount, or the project folder kosa8 agent run shares as /work, is your real folder on your computer. The checkpoint reattaches it, but does not roll its contents back. Keep git for that folder.
  • Remote side effects. Anything that left the sandbox stays done. Limiting where it can go is the job of the network allow-list.

05Other options

  • Claude Code checkpoints. Claude Code saves the files it edits and lets you rewind them with /rewind. Its documentation notes that changes made by bash commands are not tracked, so it pairs well with git for file-level undo.
  • Docker. Throwing away a container resets its filesystem, and docker commit saves a filesystem image, without memory or running processes.
  • Firecracker. Firecracker supports microVM snapshots of memory and device state, if you build and run the VMs yourself.
  • A full VM in UTM or Lima. A good fit for a long-lived workstation-style environment; snapshot support depends on the backend.
  • Filesystem snapshots. APFS local snapshots, ZFS or btrfs restore files and directories, but not running processes.

06Sources