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