Ctrlk
Contact Sales

Checkpointing

Checkpointing automatically saves a snapshot of your project's file state before any file modifications are made by AI-powered tools. This lets you safely experiment with code changes, knowing you can instantly revert back to the state before the tool was run.

For related commands and configuration, see Commands, Settings, and Settings Reference.

How it works

When a tool that modifies the file system (like write_file or replace) is proposed and awaiting your approval, the CLI automatically creates a checkpoint. This checkpoint includes:

1

A Git snapshot

A commit is made in a shadow Git repository that captures the complete state of your project files at that moment. This does not interfere with your project's own Git repository or history.

2

Conversation history

The conversation you've had with the agent up to that point is saved alongside the snapshot.

3

The tool call

The specific tool call that was about to be executed is stored, so it can be re-proposed after a restore.

Checkpoint data is stored locally on your machine. The Git snapshots are kept in the shadow repository, and the conversation history and tool call metadata are saved as JSON files in your project's temporary checkpoints directory.

Requirements

  • Git must be installed. Checkpointing uses Git internally to create snapshots. If Git is not available, checkpointing will silently fail and no snapshots will be created.

  • Your project directory must be accessible for file operations.

Enabling checkpointing

Checkpointing is disabled by default. To enable it, add the following to your settings.json (located at ~/.tabnine/agent/settings.json). For more about CLI configuration, see Settings and Settings Reference:

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

A restart of Tabnine CLI is required after changing this setting.

This setting is not available through the /settings menu — configure it directly in settings.json.

Using the /restore command

Once checkpointing is enabled, snapshots are created automatically before file-modifying tool calls. The /restore command lets you manage and revert to these snapshots.

The /restore command is only available when checkpointing is enabled. If you don't see it in your command list, verify that checkpointing is enabled in your settings.

List available checkpoints

To see all available checkpoints for the current session, run /restore with no arguments:

The CLI displays a list of checkpoint names. Each name includes a timestamp, the file that was being modified, and the tool that was about to run. For example:

Restore a specific checkpoint

To restore your project to a specific checkpoint, pass the checkpoint name as an argument:

For example:

Tab completion is available — start typing and press Tab to autocomplete checkpoint names.

After restoring:

  • All files in your project are reverted to the state captured in the snapshot.

  • The conversation history is restored to the point when the checkpoint was created.

  • The original tool call is re-proposed, allowing you to run it again or skip it.

Limitations

  • Checkpoints are scoped to the current session. The checkpoints directory is cleaned up automatically when a new session starts, so previous checkpoints are no longer available after restarting the CLI.

  • Only file-modifying tool calls (like write_file and replace) trigger automatic checkpoints. Shell commands that modify files do not trigger checkpoints.

  • Checkpoints are not created when running in YOLO mode (--yolo or --approval-mode=yolo), because tools are executed immediately without an approval pause.

  • Restoring a checkpoint reverts all file changes back to the saved state — selective file restoration is not supported.

Related docs

Last updated

Was this helpful?