> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace checkpoints

> Snapshot your workspace with rbs checkpoint and roll back AI or agent changes safely — automatic save points before every agent turn, manual ones whenever you want.

A **checkpoint** captures the state of your workspace files at a point in time, so
you can revert to it later. Think of it as a save point: create one before a risky
change — or let ReasonOS create one for you before every agent turn — and roll
back if you don't like what happened.

Checkpoints are **independent of git**. They snapshot file content directly, so a
revert always works regardless of what you've done with git in the meantime —
commits, rebases, stashes. Restores write bytes back to disk; there is no merging
and there are no conflicts.

<Note>
  Checkpoints are local, disposable state on your branch node (they live under the
  workspace's `.rbs/` directory, which is not committed). They do not travel with
  the branch through git, and they are meant for short-lived undo — old ones are
  pruned. Anything you want to keep, commit.
</Note>

## Automatic checkpoints

When you chat with the agent in the ReasonOS editor, the branch node creates a
checkpoint **before the agent starts processing each message** — synchronously, so
the snapshot always captures the true pre-modification state of your files. The
editor shows these alongside the conversation, which is what powers the
per-turn **Revert** action: undo everything an agent turn did with one click.

The same happens before the agent responds to an `@agent` mention on a
[task board](/workflow/task-board) card, since the mention may ask for real work
on files.

Automatic checkpoints record which agent session they belong to, so you can list a
session's save points and walk them as a chain (see below).

## Manual checkpoints

Create one yourself before anything you might want to unwind:

```bash theme={null}
rbs checkpoint create                              # snapshot all modified files
rbs checkpoint create -m "before refactor"         # with a description
rbs checkpoint create src/main.go src/util.go      # specific files only
rbs checkpoint create --session abc123             # tie it to an agent session
```

With no file arguments, all files that git reports as modified are included.

<Tip>
  `rbs cp` is an alias for `rbs checkpoint`.
</Tip>

## Inspecting and reverting

```bash theme={null}
rbs checkpoint list                       # all checkpoints, most recent first
rbs checkpoint list --session abc123      # just one agent session's
rbs checkpoint diff abc12345              # what changed since that checkpoint
rbs checkpoint revert abc12345            # restore the workspace to it
```

Checkpoint IDs can be abbreviated to any unique prefix.

`diff` shows which files have been **modified**, **added**, or **deleted** since
the checkpoint was taken — a preview of exactly what `revert` will touch.

`revert` restores every snapshotted file to its checkpointed content. Files that
did not exist when the checkpoint was created are deleted; files modified since
are overwritten. If you have the ReasonOS editor connected to the same branch
node, open tabs and the file tree refresh automatically after a revert.

<Warning>
  `revert` overwrites current file content without asking. Run
  `rbs checkpoint diff <id>` first if you're not sure what will change — or create
  a fresh checkpoint before reverting, so the revert itself is undoable.
</Warning>

## Session chains

Checkpoints created within one agent session link to each other, oldest to newest.
`chain` walks those links back to the start of the session:

```bash theme={null}
rbs checkpoint chain abc12345
```

That gives you the session's timeline of save points — one per conversation turn
for automatic checkpoints — so you can pick how far back to roll rather than only
undoing the last turn.

## Cleaning up

```bash theme={null}
rbs checkpoint delete abc12345      # remove one checkpoint
rbs checkpoint prune                # remove checkpoints older than 24h
rbs checkpoint prune --hours 48     # ...or older than 48h
```

`prune` also garbage-collects the underlying content that no remaining checkpoint
references. Snapshots are content-addressed and compressed, so checkpoints are
cheap — but they are still meant to be short-lived working state, not an archive.

## Command reference

| Command                            | What it does                                         |
| ---------------------------------- | ---------------------------------------------------- |
| `rbs checkpoint create [files...]` | Create a checkpoint (`-m` message, `--session` link) |
| `rbs checkpoint list`              | List checkpoints (`--session`, `--limit`)            |
| `rbs checkpoint diff <id>`         | Show workspace changes since a checkpoint            |
| `rbs checkpoint revert <id>`       | Restore the workspace to a checkpoint                |
| `rbs checkpoint chain <id>`        | Show a checkpoint's parent chain within its session  |
| `rbs checkpoint delete <id>`       | Delete a checkpoint                                  |
| `rbs checkpoint prune [--hours N]` | Remove old checkpoints and unreferenced content      |