When a run, a tool call or a command writes to several files, Monofile groups those writes into one changeset with a summary of what it did. That grouping lets you undo an entire run in one step instead of hunting through nine files for nine versions.

## What creates a changeset

| Kind | What it groups |
|---|---|
| Assistant run | Every file the built-in assistant wrote during one run, linked to the conversation it came from |
| Tool call | The writes of one REST or MCP tool call |
| Client run | Every write of one CLI invocation, so a multi-file `monofile push` is a single unit |
| Shell command | The file changes a single `bash` command left behind |
| Sync push | The files one sync round pushed from a local folder or the desktop app |
| Checkpoint | The snapshots a file or folder checkpoint captured |
| Revert | The content a revert replaced |

Two things never become a changeset. Your own edits in the editor are plain versions on the file, because there is no run to group them into. A run that writes nothing leaves no changeset.

## What a changeset records

- An id, the kind above, and when it happened.
- A summary written from the files it touched, in the form `Created /a.md · Edited /b.md (2 files)`. A checkpoint carries your name instead.
- One entry per file, with the path and whether the run created or edited it.
- Whether you have reviewed it, so the assistant keeps showing you a change you have not looked at yet.
- For assistant runs, the conversation it belongs to.

## Where you see them

**In the chat.** After the assistant writes anything, a review card appears under the conversation. Open it for a file list with a diff per file, then choose **Keep all**, **Revert all**, or act on single files. The card survives a reload and a change of device, and it comes back when you reopen an old conversation, so a run you never watched still gets reviewed. [[Reviewing Changes]] covers that panel in detail.

**In a file's history.** Versions are grouped by the changeset that produced them, and the run's summary is the label you see on the row.

**From the terminal.**

```bash title="Terminal"
monofile changesets list --limit 10
monofile changesets list --path /Projects/report.md
```

**From the API.** `list_changesets` returns them newest first with their file lists, and takes an optional `path` to show only the changesets that touched one file:

```http
POST /api/tools/list_changesets
{"limit": 10, "path": "/Projects/report.md"}
```

```bash title="Terminal"
curl -X POST "https://www.monofile.ai/api/tools/list_changesets" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10, "path": "/Projects/report.md"}'
```

Listing needs the `files:read` scope.

## Why the grouping matters

A run is the unit you judge. You do not think "the third edit to `auth.py` was wrong", you think "that refactor was a bad idea". A changeset matches that unit: one id, one summary, one decision.

It also makes a complete undo possible. Reverting a changeset restores each file to its state before the run started, even a file the run wrote twice, and deletes the files the run created. Doing that by hand across nine files is where people make mistakes.

Changesets are per workspace, so a personal workspace and a team workspace keep separate lists, and you only ever see your own.

## Next steps

:::cards
- [[Reverting Safely]] — Restore a file or undo a whole run, and what happens on a conflict.
- [[Reviewing Changes]] — The diff view and the changeset card: keep or revert everything an agent touched.
- [[How Versioning Works]] — Automatic version capture on every write, and how long versions last.
- [[Checkpoints]] — Named snapshots of a file or a folder subtree you can return to.
:::