Checkpointing

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:

1. 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.

2. Saves your conversation history up to that point

3. Records the tool call that was about to run

This three-part checkpoint allows you to:

• Revert all files to their previous state
• Resume the conversation from where you were
• Review and potentially re-run the original tool call

All checkpoint data is stored locally on your machine:

• Git snapshots in ~/.bob/history/<project_hash>
• Conversation history and tool calls in ~/.bob/tmp/<project_hash>/checkpoints

Enabling checkpointing

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

Settings file (persistent)

To enable checkpointing for all sessions:

1. Edit your settings.json file
2. Add the following configuration:

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

Managing checkpoints

Viewing available checkpoints

To see all saved checkpoints for your current project:

/restore

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

• Timestamp
• Modified file name
• Tool that was used

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

Restoring a checkpoint

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:

1. Revert your files to their previous state
2. Restore the conversation history
3. Re-propose the original tool call

Best practices

• 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

Limitations

• 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