Checkpointing enables session-scoped snapshots for tracking file changes using Git-like commands. This feature creates a shadow bare git repository to manage file state across your chat session.
Checkpointing provides version control for your chat session, allowing you to:
kiro-cli settings chat.enableCheckpoint true
Or use the experiment command:
/experiment # Select "Checkpointing" from the list
/checkpoint initCheckpointing creates a temporary bare git repository that:
Manually enable checkpoints (required if not in a git repository):
/checkpoint init
Show turn-level checkpoints with file statistics:
/checkpoint list [--limit N]
Example output:
[0] 2025-09-18 14:00:00 - Initial checkpoint [1] 2025-09-18 14:05:31 - add two_sum.py (+1 file) [2] 2025-09-18 14:07:10 - add tests (modified 1) [3] 2025-09-18 14:10:45 - refactor algorithm (modified 1)
Show tool-level checkpoints under a specific turn:
/checkpoint expand <tag>
Example:
> /checkpoint expand 2 [2] 2025-09-18 14:07:10 - add tests └─ [2.1] fs_write: Add minimal test cases to two_sum.py (modified 1)
Compare checkpoints or compare with current state:
/checkpoint diff <tag1> [tag2|HEAD]
Examples:
/checkpoint diff 1 2 # Compare checkpoint 1 to checkpoint 2 /checkpoint diff 1 HEAD # Compare checkpoint 1 to current state /checkpoint diff 1 # Same as above (HEAD is default)
Restore to a checkpoint:
/checkpoint restore [<tag>] [--hard]
Interactive picker: If no tag specified, shows interactive selection
Restore options:
--hard: Makes workspace exactly match checkpoint; deletes tracked files created after itExamples:
/checkpoint restore 2 # Restore to checkpoint 2 (soft) /checkpoint restore 2 --hard # Restore to checkpoint 2 (hard) /checkpoint restore # Interactive selection
Delete the session shadow repository:
/checkpoint clean
Warning: This removes all checkpoint data for the current session.
Reverts tracked changes and deletions but keeps new files:
/checkpoint restore 2
What happens:
Use when:
Makes workspace exactly match checkpoint state:
/checkpoint restore 2 --hard
What happens:
Use when:
⚠️ Warning: Hard restore permanently deletes files. Use with caution.
> Help me refactor this function # Kiro makes changes... > /checkpoint list [0] Initial checkpoint [1] Refactored function (modified 1) > Actually, let's try a different approach > /checkpoint restore 0 # Back to original state > Now try using a different pattern...
> Implement feature A # Implementation complete > /checkpoint list [1] Implemented feature A (modified 2) > Now show me an alternative implementation # Alternative implementation > /checkpoint list [2] Alternative implementation (modified 2) > /checkpoint diff 1 2 # See differences between approaches
> /checkpoint list [0] Initial state [1] Added user model (+1 file) [2] Added authentication (+2 files) [3] Added tests (modified 3) > /checkpoint expand 2 [2] Added authentication └─ [2.1] fs_write: Create auth.py (+1 file) └─ [2.2] fs_write: Update routes.py (modified 1)
> /checkpoint list [0] Working code [1] Attempted optimization (modified 1) [2] More changes (modified 2) # Realize the optimization broke things > /checkpoint restore 0 # Back to working state
When you restore to a checkpoint, the conversation history also unwinds to that point. This means:
This ensures consistency between file state and conversation context.
/checkpoint list to see progress/checkpoint clean to remove session data/checkpoint list periodically/checkpoint diff to see changesVerify it's enabled:
kiro-cli settings chat.enableCheckpoint
Initialize manually (if not in git repo):
/checkpoint init
Check for errors: Look for error messages in chat
Verify checkpoint exists:
/checkpoint list
Check file permissions: Ensure write access to files
Try soft restore first: Use default restore before --hard
If shadow repository becomes corrupted:
Clean and reinitialize:
/checkpoint clean /checkpoint init
Restart session: Start a new chat session
⚠️ Checkpointing creates temporary git repositories that are cleaned up when the session ends.
⚠️ Use caution with --hard restore as it permanently deletes files.
⚠️ Checkpoints are session-scoped and don't persist across sessions.
⚠️ Conversation history unwinds when restoring to maintain consistency.
Checkpointing