packages/kilo-docs/pages/code-with-ai/features/checkpoints.md
Checkpoints automatically version your workspace files during Kilo Code tasks, enabling non-destructive exploration of AI suggestions and easy recovery from unwanted changes.
Checkpoints let you:
{% tabs %} {% tab label="VSCode" %}
Checkpoints (called snapshots in the new extension) are enabled by default. They are configured via the snapshot key in your config file (kilo.jsonc or ~/.config/kilo/kilo.jsonc):
{
"snapshot": true
}
You can also toggle this in Settings:
{% callout type="info" %}
Unlike the legacy extension which used a separate shadow Git repository, the new extension uses a dedicated snapshot Git repository stored outside your project. Your project's .git history is never modified by the snapshot system.
{% /callout %}
{% /tab %} {% tab label="CLI" %}
Checkpoints are controlled by the snapshot boolean in your kilo.jsonc configuration file:
{
"snapshot": true
}
When enabled, the system automatically captures snapshots at each step of a task.
{% /tab %} {% tab label="VSCode (Legacy)" %}
Access checkpoint settings in Kilo Code settings under the "Checkpoints" section:
Open Settings by clicking the gear icon {% codicon name="gear" /%} → Checkpoints
Check or uncheck the "Enable automatic checkpoints" checkbox
{% image src="/docs/img/checkpoints/checkpoints.png" alt="Checkpoint settings in Kilo Code configuration" width="500" /%}
{% /tab %} {% /tabs %}
{% tabs %} {% tab label="VSCode" %}
The new extension uses git-based snapshots to track your workspace state. A dedicated Git repository (with a detached work tree pointing at your project) is created outside your project directory to store snapshot data — your project's own .git history is never touched.
Snapshots are captured automatically at the boundaries of each model call within an agent turn:
A single user message can produce multiple steps. For example, if the agent edits a file, runs a command, sees the output, and then edits another file, each model call in that sequence gets its own snapshot pair. The system records which files changed in each step.
However, while snapshots are taken at each step boundary, the revert UI operates at the user message level. You can only revert to the point just before a user message was sent — you cannot revert to an intermediate step within a single agent response.
{% callout type="warning" %} Revert granularity is per user message, not per individual step or file edit. If the agent makes changes across multiple steps within a single response, reverting will undo all of those changes at once. {% /callout %}
{% callout type="info" %}
Snapshots respect your .gitignore rules. Files ignored by Git (such as node_modules/, dist/, or .env) are excluded from snapshots.
{% /callout %}
{% /tab %} {% tab label="VSCode (Legacy)" %}
{% callout type="info" title="Important Notes" %}
{% /callout %}
Kilo Code captures snapshots of your project's state using a shadow Git repository, separate from your main version control system. These snapshots, called checkpoints, automatically record changes throughout your AI-assisted workflow—whenever tasks begin, files change, or commands run.
Checkpoints are stored as Git commits in the shadow repository, capturing:
{% /tab %} {% /tabs %}
{% tabs %} {% tab label="VSCode" %}
Checkpoints are integrated directly into your chat interface. Each agent turn that modified files shows a collapsible diff summary listing the changed files with addition/deletion counts.
Click the diff summary on any agent turn to expand it and see which files were modified. Click an individual file to open a side-by-side diff in the VS Code editor.
Every user message in the chat that has a corresponding agent response shows a Revert to here button (a left-arrow icon) when you hover over it:
{% image src="/docs/img/checkpoints/revert-to-here-button.png" alt="Revert to here button shown on hover over a user message" width="350" /%}
The revert button appears on user messages only — these are the revert points in the conversation. You revert to the state your workspace was in just before a given user message was sent. There is no way to revert to a point partway through an agent response.
Clicking Revert to here does two things:
The button is only active when the agent is idle. While the agent is running, the button is disabled to prevent reverting mid-operation.
After reverting, a Revert Banner appears at the bottom of the chat. The banner shows:
The banner provides two actions:
While in a reverted state, you have two choices:
{% callout type="tip" %} Reverting is non-destructive until you send a new message. You can freely revert and redo to compare different states of your code without losing anything. {% /callout %}
{% /tab %} {% tab label="CLI" %}
Checkpoints are captured automatically at each step of a task. In the CLI terminal interface, checkpoints appear as revert points in the conversation. You can revert to any point by selecting the corresponding message.
{% /tab %} {% tab label="VSCode (Legacy)" %}
Checkpoints are integrated directly into your workflow through the chat interface.
Checkpoints appear directly in your chat history in two forms:
Initial checkpoint marks your starting project state {% image src="/docs/img/checkpoints/checkpoints-1.png" alt="Initial checkpoint indicator in chat" width="500" /%}
Regular checkpoints appear after file modifications or command execution {% image src="/docs/img/checkpoints/checkpoints-2.png" alt="Regular checkpoint indicator in chat" width="500" /%}
Each checkpoint provides two primary functions:
To compare your current workspace with a previous checkpoint:
Locate the checkpoint in your chat history
Click the checkpoint's View Differences button
{% image src="/docs/img/checkpoints/checkpoints-6.png" alt="View Differences button interface" width="100" /%}
Review the differences in the comparison view:
{% image src="/docs/img/checkpoints/checkpoints-3.png" alt="View differences option for checkpoints" width="800" /%}
To restore a project to a previous checkpoint state:
Locate the checkpoint in your chat history
Click the checkpoint's Restore Checkpoint button
{% image src="/docs/img/checkpoints/checkpoints-7.png" alt="Restore checkpoint button interface" width="100" /%}
Choose one of these restoration options:
{% image src="/docs/img/checkpoints/checkpoints-4.png" alt="Restore checkpoint option" width="300" /%}
Restore Files Only - Reverts only workspace files to checkpoint state without modifying conversation history. Ideal for comparing alternative implementations while maintaining chat context, allowing you to seamlessly switch between different project states. This option does not require confirmation and lets you quickly switch between different implementations.
Restore Files & Task - Reverts both workspace files AND removes all subsequent conversation messages. Use when you want to completely reset both your code and conversation back to the checkpoint's point in time. This option requires confirmation in a dialog as it cannot be undone.
{% image src="/docs/img/checkpoints/checkpoints-9.png" alt="Confirmation dialog for restoring checkpoint with files & task" width="300" /%}
{% /tab %} {% /tabs %}
{% tabs %} {% tab label="VSCode" %}
The snapshot system consists of:
Snapshot Git Repository: A dedicated Git repository created outside your project at ~/.local/share/kilo/snapshot/<project-id>/<worktree-hash>/. This stores all snapshot tree objects without affecting your project's Git history. Each worktree gets its own snapshot repository, identified by a hash of the worktree path.
Step-level Snapshots: The agent runtime automatically runs git write-tree against your workspace before and after each agent step. The resulting tree hashes are stored alongside the conversation messages.
Patch Records: After each step, the system records which files were modified. These patch records enable targeted file-level reverts rather than full-workspace restores.
When you click "Revert to here" on a message:
When you click "Redo All" (unrevert):
git checkout-indexSnapshot data is stored per-project and is periodically cleaned up. A background process runs git gc --prune=7.days every hour, which removes unreachable snapshot objects older than 7 days. Because snapshots are stored as raw tree hashes (not refs or commits), older snapshots may be pruned by garbage collection even if a session still references them.
When using the Agent Manager with git worktrees, each worktree gets its own isolated snapshot repository. This prevents snapshot data from one worktree interfering with another while sharing underlying Git objects for storage efficiency.
{% /tab %} {% tab label="VSCode (Legacy)" %}
The checkpoint system consists of:
Shadow Git Repository: A separate Git repository created specifically for checkpoint tracking that functions as the persistent storage mechanism for checkpoint state.
Checkpoint Service: Handles Git operations and state management through:
UI Components: Interface elements displayed in the chat that enable interaction with checkpoints.
When restoration executes, Kilo Code:
Checkpoints are task-scoped, meaning they are specific to a single task.
Checkpoint comparison uses Git's underlying diff capabilities to produce structured file differences:
The checkpoint system uses intelligent file exclusion to track only relevant files:
The system has comprehensive built-in exclusion patterns that automatically ignore:
node_modules/, dist/, build/).cache/, .tmp/, .bak).env)These patterns are written to the shadow repository's .git/info/exclude file during initialization.
The checkpoint system respects .gitignore patterns in your workspace:
.gitignore won't trigger checkpoint creationThe .kilocodeignore file (which controls AI access to files) is separate from checkpoint tracking:
.kilocodeignore but not by .gitignore will still be checkpointedThis separation is intentional, as .kilocodeignore limits which files the AI can access, not which files should be tracked for version history.
Checkpoints do not support nested Git repositories. The working directory must be a single Git repository for checkpoints to function properly.
.git directories are not supported and checkpoints will be disabled.git directory, which is incompatible with checkpoint trackingOperations are queued to prevent concurrent Git operations that might corrupt repository state. This ensures that rapid checkpoint operations complete safely even when requested in quick succession.
{% /tab %} {% /tabs %}
Checkpoints require Git to be installed on your system.
Install with Homebrew (recommended):
brew install git
Alternative: Install with Xcode Command Line Tools:
xcode-select --install
Verify installation:
git --versiongit version 2.40.0Download Git for Windows:
Run the installer:
Verify installation:
git --versiongit version 2.40.0.windows.1Debian/Ubuntu:
sudo apt update
sudo apt install git
Fedora:
sudo dnf install git
Arch Linux:
sudo pacman -S git
Verify installation:
git --version