Why use checkpointing?

Safety net: Experiment with code changes without fear of breaking your project
Easy rollback: Restore your project to a previous state with a single command
Conversation preservation: Return to the exact conversation context when a change was made
Non-intrusive: Works alongside your existing Git workflow without interference

How checkpointing works

When you approve a file-modifying operation (such as write_file or replace), Bob Shell automatically:

Creates a Git snapshot in a shadow repository (~/.bob/history/<project_hash>)

Note: This shadow repository is separate from your project's Git repository and won't interfere with your normal Git workflow.
Saves your conversation history up to that point
Records the tool call that was about to run

This three-part checkpoint allows you to:

All checkpoint data is stored locally on your machine:

Checkpointing is disabled by default. You can enable it in two ways:

To enable checkpointing for all sessions:

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

To see all saved checkpoints for your current project:

/restore

Bob Shell will display a list of checkpoint files with names that include:

Example: 2025-06-22T10-00-00_000Z-my-file.txt-write_file

To restore your project to a specific checkpoint:

/restore <checkpoint_file>

For example:

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

This will:

Enable for critical work: Always use checkpointing when working on important code
Test before relying: Try the restore functionality on a non-critical project first
Regular commits: Continue making regular Git commits for meaningful changes
Checkpoint cleanup: Periodically remove old checkpoints you no longer need
Combine with version control: Use checkpointing alongside your normal Git workflow for maximum safety

Checkpointing only tracks files that are already under version control or have been modified by Bob Shell
External changes made outside of Bob Shell won't be included in checkpoints
Very large projects may experience slightly slower checkpoint creation times