Skip to content

checkpoints.mdx

Latest commit

 

History

History
118 lines (77 loc) · 6.37 KB

checkpoints.mdx

File metadata and controls

118 lines (77 loc) · 6.37 KB
Raw
title Checkpoints
sidebarTitle Checkpoints
description Roll back code changes while keeping your conversation. Experiment freely.

Checkpoints let you undo code changes without losing your conversation. Every time LUMI modifies a file or runs a command, it saves a snapshot of your project files. You can restore to any checkpoint, keeping the context you've built while reverting the code.

This changes how you work with LUMI. Instead of carefully reviewing every change before approving, you can let LUMI move fast and roll back if something goes wrong. The cost of a mistake drops to nearly zero.

Checkpoints are enabled by default. See [Enable or Disable Checkpoints](#enable-or-disable-checkpoints) if you need to turn them off.

How It Works

LUMI maintains a shadow Git repository separate from your project's actual Git history. After each tool use (file edits, commands, etc.), LUMI commits the current state of your files to this shadow repo. Your main Git repository stays untouched.

This means:

  • Your Git history remains clean and under your control
  • Checkpoints capture everything, including files not tracked by Git
  • You can restore to any point in a task without affecting commits you've made
  • Checkpoints persist across editor sessions

Each checkpoint captures the complete file state at that moment. If LUMI edits three files in sequence, you get three checkpoints and can restore to any of them independently.

Enable or Disable Checkpoints

Checkpoints are enabled by default. To toggle them:

  1. Open LUMI settings (gear icon in the LUMI sidebar)
  2. Scroll to the "Feature Settings" section
  3. Toggle "Enable Checkpoints"
For very large repositories, checkpoints may use significant storage and slow down LUMI as it commits file snapshots after each tool use. Consider disabling them if you notice performance issues.

Viewing and Comparing Changes

After each tool use, a checkpoint indicator appears in your conversation. Look for a bookmark icon labeled "Checkpoint" with a dotted line connecting to Compare and Restore buttons.

Implementation (code paths)

Checkpoints are implemented under src/integrations/checkpoints/:

Component Role
CheckpointTracker.ts Creates commits after tool use, diff/restore operations
CheckpointGitOperations.ts Shadow Git init, staging, nested-repo handling
CheckpointUtils.ts Storage path under VS Code globalStorage/checkpoints/{cwdHash}/.git
factory.ts Wires tracker into tasks; multi-root via MultiRootCheckpointManager

Settings: enableCheckpointsSetting (global state, default on). Toggle in LUMI Settings → Feature Settings → Enable Checkpoints, or via updateSettings in src/core/controller/state/updateSettings.ts.

Safety: Checkpoints refuse protected directories (home, Desktop, Documents, Downloads). Git must be installed on the machine.

Restore modes map to task message handlers that call CheckpointTracker reset/diff APIs and trim conversation history after the selected checkpoint.

Click Compare to open a diff view showing exactly what changed at that checkpoint. This opens in your editor's diff viewer, letting you see additions, deletions, and modifications across all affected files.

This is useful when LUMI makes changes you want to understand before deciding whether to keep them. You can review the diff, then either continue or restore to undo.

Restoring Checkpoints

Click Restore next to any step to open the restore menu. You have three options:

Option What It Does When to Use It
Restore Files Reverts your project's files to the snapshot at this checkpoint Undoing code changes while keeping the conversation
Restore Task Only Deletes messages after this point, does not affect files Trying a different prompt while keeping current code
Restore Files & Task Reverts files and deletes messages after this point Starting over completely from a known good state

The right choice depends on what went wrong:

  • If the conversation is productive but the code changes broke something, use Restore Files. LUMI keeps all the context you've discussed and can try a different implementation.

  • If LUMI's code changes are good but the conversation went off track, use Restore Task Only. You keep the files and can guide the conversation differently.

  • If you want to start over from a clean slate, use Restore Files & Task. This resets both your files and the conversation to that checkpoint.

When to Use Checkpoints

Scenario Recommended Action
LUMI refactored code and broke something Restore Files, ask for a different approach
Experimenting with multiple solutions Compare each checkpoint, restore to the best one
LUMI misunderstood your intent Restore Files & Task, rephrase your request
Want to try a different prompt Restore Task Only, keep the files, resubmit
Reviewing changes before committing to Git Use Compare to inspect, then commit manually
Testing risky changes Let LUMI proceed, restore if it fails

Working with Auto-Approve

Checkpoints make auto-approve practical. Without checkpoints, auto-approve feels risky because LUMI can make many changes before you notice a problem. With checkpoints, you can let LUMI work autonomously and roll back if needed.

A typical workflow:

  1. Enable auto-approve for file edits and commands
  2. Let LUMI work through your task quickly
  3. Review the final result
  4. If something is wrong, restore to the last good checkpoint
  5. Give LUMI more specific guidance

This approach is faster than reviewing every change individually, and checkpoints provide the safety net.

Checkpoints and Message Editing

The message editing feature integrates with checkpoints. When you edit a previous message and select "Restore All," LUMI restores your files to the checkpoint at that point before resubmitting your edited message.

This lets you fix a poorly worded prompt and undo all the changes that resulted from it in one action.

Related docs