An agent can change several files before you see the result. Git Checkpoints & Restore gives you a recovery point tied to the prompt that started the run. If the work takes the project in the wrong direction, you can return the repository and conversation to the state from before that prompt.
What problem this solves
You may have local edits that are not ready for a commit. You may also want to let Tarsk refactor a large part of a project without stopping to review every change. A checkpoint protects those edits while the agent works.
Tarsk creates a Git-backed checkpoint when an agent run starts. The checkpoint includes tracked files and untracked files in the working tree, along with the staged state. Tarsk keeps the recovery point attached to the user message that launched the run, so you can find the right restore action in a long thread.
Restore affects the whole working tree and the conversation from that prompt forward. It is useful for abandoning an agent run, then continuing from a known state.
Requirements and setup
You need these conditions for a checkpoint to work:
- The thread must point to a Git repository.
- The repository must contain at least one commit.
- The project path must be available to Tarsk.
- The checkpoint creation request must finish before its timeout.
Tarsk attempts to create a checkpoint when you send a prompt that starts an agent run. Tarsk records a checkpoint reference for a clean working tree as well.
Use Git Checkpoints & Restore
1. Start from the project state you want to protect
Open a Git-backed thread and review your current files. Keep any local edits you want to preserve in the working tree. You can leave changes staged, unstaged, or untracked.
Commit the repository at least once before using checkpoints. An uninitialized repository cannot provide a restore point.
2. Send the agent prompt
Describe the task in the chat and send it. For example:
Refactor the authentication flow to use the new session helper. Update the tests and explain any behavior changes.Tarsk records the checkpoint after it adds your prompt and before the agent begins to modify files. Your pre-existing changes remain in the working tree while the agent runs.
The restore control belongs to the user message that started the run. It may be unavailable while the thread is streaming, pending, or processing.
3. Review the result
Wait for the run to finish, then inspect the diff and test results. Use the normal Git review tools when you want to keep some of the work. The restore control appears when you hover over the triggering user message and has a circular-arrow icon.
The control may be disabled when Tarsk could not create a checkpoint for that prompt. Hover over it to read the reason. Common causes include a missing Git repository, a repository with no commits, or a checkpoint request that timed out.
4. Select Restore checkpoint
Hover over the user message, then select Restore checkpoint. Tarsk opens a confirmation dialog with text such as:
Restore to the checkpoint before “Refactor the authentication flow…” was started?
Read the prompt in the dialog. Select Cancel if you want to keep the current work. Select Restore checkpoint to proceed.
5. Confirm the restored state
Tarsk removes current tracked changes and untracked files, then reapplies the saved checkpoint. It also removes the triggering prompt and all later messages from the conversation. The chat reloads at the earlier point, and Git status refreshes.
A successful restore shows Checkpoint restored with a message that the working tree and conversation returned to before the prompt. If Git cannot apply the checkpoint, Tarsk shows Restore failed with the error detail and leaves the success state unset.
A practical example
You have an unfinished edit in src/app.ts. You ask Tarsk to refactor authentication, and the agent changes that file plus several related modules. The result introduces a behavior you do not want.
Restore the checkpoint from the authentication prompt. Tarsk brings back your unfinished src/app.ts edit, removes the agent’s changes, and deletes that prompt and its later conversation from the thread. You can revise the request and start again from the same project state.
If you made unrelated edits after the agent started, restore removes those edits too. Review the current working tree before you confirm.
Advanced tips
Use Review → Revert for one file
Checkpoint restore resets the entire working tree and the related conversation. Choose Revert in the Git Ops Review panel when you want to discard changes from one file and keep the rest of the run.
Commit work you want to keep
A checkpoint is a recovery point for an agent run. It is not a commit, remote backup, or permanent version history. Commit work that you want to preserve before you run another task.
Check the message before restoring
Each checkpoint belongs to one user prompt. In a long thread, hover over the message that started the run you want to undo. Restoring an earlier prompt also removes every later message in that thread.
Common pitfalls
The restore action is unavailable
Wait until the run finishes. If the action stays unavailable, check that the thread uses a project inside a Git repository with at least one commit. Tarsk creates checkpoints on a best-effort basis, so a timeout or Git error can leave a prompt without a restore point.
The repository changed after the checkpoint
Restore discards current tracked changes and untracked files before it applies the saved state. Copy or commit any work you want to keep first. This includes edits unrelated to the agent run.
The checkpoint was deleted from Git
Tarsk needs the saved checkpoint to remain available. If you remove or alter its Git stash entry, restore can fail. The restore action reports the failure instead of claiming that the repository returned to the earlier state.
Summary
Git Checkpoints & Restore protects the working tree before an agent run and links that recovery point to the exact user prompt. After the run finishes, hover over that prompt and select Restore checkpoint to return the files and conversation to their earlier state.
Use restore for a full run rollback. Use Git Ops Review → Revert for a single-file change, and commit important work before you let the agent make broad edits.