# 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](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/commands), [Settings](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/settings), and [Settings Reference](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/settings/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:

{% stepper %}
{% step %}

#### 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.
{% endstep %}

{% step %}

#### Conversation history

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

{% step %}

#### The tool call

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

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](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/settings) and [Settings Reference](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/settings/settings-reference):

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

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

{% hint style="info" %}
This setting is not available through the [`/settings` menu](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/settings) — configure it directly in `settings.json`.
{% endhint %}

## Using the `/restore` command

Once checkpointing is enabled, snapshots are created automatically before file-modifying tool calls. The [`/restore` command](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/commands) lets you manage and revert to these snapshots.

{% hint style="info" %}
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.
{% endhint %}

### List available checkpoints

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

```bash
/restore
```

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:

```bash
2025-06-22T10-00-00_000Z-my-file.txt-write_file
```

### Restore a specific checkpoint

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

```bash
/restore <checkpoint-name>
```

For example:

```bash
/restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file
```

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

* [Commands](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/commands)
* [Settings](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/settings)
* [Settings Reference](https://docs.tabnine.com/main/getting-started/tabnine-cli/features/settings/settings-reference)
* [FAQ](https://docs.tabnine.com/main/getting-started/tabnine-cli/troubleshooting/faq)