Work with agents / Local workspaces
Go back with checkpoints
An agent made a good change, then broke it with the next one. Or you closed a workspace, and now you want its work back. A checkpoint saves the files of a workspace, so you can put the workspace back, or start a new workspace from it.
3 min read
Checkpoints are kept outside your repository, and they stay after you close the workspace.
1. Save a checkpoint
src ws checkpoint api --label "tests pass"
src prints the name of the checkpoint, for example Saved api as cp-2 (tests pass). Checkpoints of a workspace are numbered from cp-1.
A checkpoint holds:
- The tracked files and the new files of the workspace.
- Its baseline, its time and its label.
- The keys of its dependency layers, for example of
node_modules.
A checkpoint does not hold:
- Ignored files, for example
node_modulesand build output. - Untracked
.envfiles and other untracked files whose name starts with.env.
If files change while src reads them, it reads them again. If they keep changing, src saves the checkpoint and says that it can mix two moments.
Tip
src also saves a checkpoint before each restore, close, sync and accept. When you restore the checkpoint from before a sync, the baseline of the workspace goes back too.
2. Put a workspace back
src ws restore api@cp-2
You can also give the label: src ws restore "api@tests pass".
srcsaves the current state as a new checkpoint. The output names it, so you can undo the restore with that name.- It writes the files of the old checkpoint.
- It deletes the files that the old checkpoint does not have.
- If the old files have another lockfile, it makes that dependency layer again, for example
node_modules. Layers whose key did not change stay as they are.
A restore changes only files and dependency layers. Other ignored files and untracked .env files stay as they are. It does not restore running processes, what an agent remembers, or changes outside the folder.
3. Start a new workspace from a checkpoint
src ws create api-retry --from api@cp-2
This works also after you closed api. The new workspace starts at the checkpoint, with a clean git status.
Done
You can try a risky change, and go back in one command if it fails.
How long checkpoints stay
The checkpoints of an open workspace stay until you close it. For a closed workspace, src ws gc applies this rule:
- Every checkpoint stays for 14 days.
- After that, only the last checkpoint stays, until it is 60 days old.
src ws gc
gc also deletes base folders that no open workspace uses.
Where checkpoints are kept
Each repository has one SQLite file in the data folder of src:
| OS | Data folder |
|---|---|
| Windows | %LOCALAPPDATA%\TanStackSource\ws |
| macOS | ~/Library/Application Support/TanStackSource/ws |
| Linux | $XDG_DATA_HOME/tanstack-source/ws, or ~/.local/share/tanstack-source/ws |
Each checkpoint is saved in one transaction. If src stops during a save, the older checkpoints do not change. The store also keeps the files of each baseline, so a workspace still works after your repository deletes a branch or runs git gc.