Checkpoints
Feature Overview: Checkpoints are iFlow CLI's safety rollback system that automatically saves project state snapshots before AI tools modify files.
Learning Time: 5-10 minutes
Prerequisites: Understanding basic Git concepts and familiarity with file version management
What are Checkpoints
Checkpoints are a safety mechanism provided by iFlow CLI that automatically saves complete snapshots of your project state before AI tools modify the file system. This feature allows you to safely experiment and apply code changes, with the ability to immediately roll back to the state before tool execution, ensuring your project's safety.
Core Features
| Feature | Description | Advantage |
|---|---|---|
| Enabled by Default | Automatically created in YOLO and Default modes | No manual configuration required |
| Automatic Creation | Automatically saves state before file modification actions | No manual operation needed |
| Complete Snapshot | Saves files, conversations, and tool calls | Comprehensive state recovery |
| Independent Storage | Does not interfere with project Git repository | Safe isolation |
| Instant Recovery | One-click rollback to any checkpoint | Quick change reversal |
| Local Storage | All data saved locally | Privacy and security |
How It Works
Checkpoint Creation Process
Checkpoint feature supports three file modification tools: replace, write_file, and multi_edit
YOLO Mode Process
Tool Call → Synchronous Checkpoint Creation → Tool Execution → Checkpoint Complete
↓
[AI Request] → [State Snapshot] → [Safe Execution] → [State Saved]
Default Mode Process
Tool Call → User Confirmation Request → Checkpoint Creation → Tool Execution → Checkpoint Complete
↓
[AI Request] → [Awaiting Approval] → [State Snapshot] → [Safe Execution] → [State Saved]
Snapshot Content Components
1. Git State Snapshot
- Creates shadow Git repository at
~/.iflow/snapshots/<project_hash> - Captures complete state of project files
- Does not interfere with project's original Git repository
2. Conversation History
- Saves complete conversation records with AI assistant
- Includes context and interaction state
- Supports complete conversation state recovery
3. Tool Call Information
- Stores specific tool calls to be executed
- Records parameters and execution context
- Supports re-execution or modification of calls
Data Storage Locations
| Data Type | Storage Path | Description |
|---|---|---|
| Git Snapshot | ~/.iflow/snapshots/<project_hash> | Shadow Git repository |
| Conversation History | ~/.iflow/cache/<project_hash>/checkpoints | JSON format files |
| Tool Calls | ~/.iflow/cache/<project_hash>/checkpoints | Call detail records |
Detailed Feature Description
Enabling Checkpoint Feature
Checkpoint feature is enabled by default and supports YOLO mode and Default mode. When the Agent executes file modification actions, checkpoints are automatically created before the changes.
Launch Methods
Scenario 1: System with Git Installed (Recommended)
# Launch iFlow CLI normally, checkpoint feature is automatically enabled
iflow
Scenario 2: System without Git
After launching iFlow, checkpoint feature will be unavailable. The system will display a tip:
Checkpoint feature is currently unavailable. Please install Git to enable it
Scenario 3: Manually Disable Checkpoint Feature
# Disable checkpoint feature via command line parameter
iflow --no-checkpointing
Using Checkpoints
Automatic Checkpoint Creation
- Checkpoints are automatically created before file modification tools execute
- Each checkpoint has a unique timestamp and filename identifier
- System will notify when checkpoint creation is complete
Viewing Checkpoints
# Use /restore command to view all checkpoints
/restore
The command completion preview interface will display information about all available checkpoints, including timestamps and operated files.
Restoring Checkpoints
# 1. Enter /restore to view checkpoint list
/restore
# 2. Use arrow keys to select target checkpoint
# 3. Press Enter to complete the command, press Enter again to execute rollback
/restore <checkpoint-name>
Manually Cleaning Checkpoints
If you find that checkpoint cache is consuming a large amount of disk space, or want to manually clean up checkpoint history, you can use the following command to perform cleanup:
/cleanup-checkpoint
Note that the above command only deletes checkpoints under the current project path. If you want to delete checkpoint caches for other project paths, please switch to the target path, launch iFlow-CLI, and then execute the command.
Usage Examples
Basic Write Operation
User Command:
> Write "hello world" to @test.txt
System Response:
# 1. System automatically creates checkpoint
[Checkpoint] Snapshot created: 2025-11-03T15-00-20_193-test.txt-write_file
# 2. Execute file write operation
# ... File updated ...
To Rollback:
# 1. Enter /restore to view checkpoint list
/restore
# 2. Use arrow keys to select target checkpoint
# Display: 2025-11-03T15-00-20_193-test.txt-write_file
# Write "hello world" to @test.txt +1 -0
# 3. Press Enter to complete the command
/restore 2025-11-03T15-00-20_193-test.txt-write_file
# 4. Press Enter again to execute rollback, file reverts to state before write
Troubleshooting
Common Issues and Solutions
| Issue | Possible Cause | Solution |
|---|---|---|
| Checkpoint creation failed | Insufficient disk space or permission issues | Check disk space and file permissions |
| Recovery failed | Checkpoint file corrupted | Use other checkpoints or manual recovery |
| Checkpoint list empty | Feature not enabled or no modifications | Enable feature and perform file operations |
| Files missing after recovery | Incomplete checkpoint | Check Git repository status |
Security Considerations
- Irreversibility: After executing a checkpoint rollback, all changes after that checkpoint cannot be recovered. Please confirm before executing the rollback command
- IDE Mode Limitation: In Default mode with IDE enabled, changes will pop up a Preview window in the IDE requiring manual confirmation. Since users manually confirm changes, iFlow CLI will not create checkpoints, so rollback via /restore command is not possible. Only when running in terminal without IDE open can all file modification actions use checkpoint rollback
- Storage Space: Checkpoints consume disk space, regularly clean up old checkpoints
- Privacy Protection: Checkpoints contain complete conversation history, be mindful of sensitive information
- Git Conflicts: Recovery may conflict with current Git state, requiring manual handling
- Large File Handling: Checkpoints for large projects may take considerable time
Platform Compatibility
| Platform | Support Level | Special Notes |
|---|---|---|
| Windows | Full support | Path handling automatically adapted |
| macOS | Full support | Complete file system support |
| Linux | Full support | Native Git integration |