codemap_list_history
List file backup history for the current session, showing all versions available for rollback
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
filePath | string | ❌ Optional | File path to list backups for (omit to list all backups) |
Usage Examples
MCP Usage (for AI Agents like Claude)
json
{
"name": "codemap_list_history",
"arguments": {}
}Example Output
JSON Response
json
{
"success": true,
"filePath": "src/auth.ts",
"backups": [
{
"version": 1,
"timestamp": "2026-04-11T12:15:30.456Z",
"reason": "write"
},
{
"version": 2,
"timestamp": "2026-04-11T12:25:15.789Z",
"reason": "write"
},
{
"version": 3,
"timestamp": "2026-04-11T12:30:45.123Z",
"reason": "rename"
}
]
}When to Use This Tool
-
Use
- Check if a file has backup versions before attempting recovery
- Audit what files have been modified during the current session
- Determine which version to rollback to by examining timestamps
- Verify that automatic backups are working as expected
- See the complete history of changes to a specific file in the session
codemap_list_history when you need to:
Common Patterns
Pre-Rollback Check Pattern
Always check available versions before attempting rollback to choose the correct one.
Session Audit Pattern
Use this pattern during code reviews or before closing sessions to ensure important work is tracked.
1. codemap_list_history({ filePath: 'file.ts' })
2. Review versions and timestamps
3. codemap_rollback({ filePath: 'file.ts', version: N })Always check available versions before attempting rollback to choose the correct one.
Session Audit Pattern
1. codemap_list_history() at end of session
2. Review all files that were modified
3. Verify critical files have backups
4. Document changes for teamUse this pattern during code reviews or before closing sessions to ensure important work is tracked.
Pro Tips
- Session-scoped storage: Backups only exist during the current session - they're purged when you run
codemap_close - Automatic creation: CodeMap automatically creates backups before write, rename, and delete operations - no manual backup needed
- Version numbers: Versions increment sequentially within each session (1, 2, 3...), starting fresh each session
- Timestamp precision: Use timestamps to understand the timeline of changes - helps identify "good" vs "broken" versions
- Quick recovery: Combine with
codemap_rollbackfor instant file recovery without manual restoration
Best Practices
- Check backup history before running risky batch operations to ensure you can recover
- Review file history during debugging to understand when problems were introduced
- Use the timestamp information to correlate backups with specific actions or changes
- Keep sessions reasonably scoped - very long sessions accumulate many backups and can be confusing
- Document why you're rolling back in commit messages or team communication
- Remember backups are purged on session close - use git or other version control for permanent history
Common Mistakes
❌ Mistake: Assuming backups persist across sessions
✅ Instead: Remember backups are session-scoped and purged when you close the session - use git for permanent version history
❌ Mistake: Not checking available versions before rollback
✅ Instead: Always run
❌ Mistake: Forgetting backups are only created on write/rename/delete
✅ Instead: If you want a manual snapshot, use
❌ Mistake: Relying on file history as a replacement for version control
✅ Instead: Use file history for session-level recovery and git/version control for permanent project history
❌ Mistake: Not reviewing timestamps when choosing which version to restore
✅ Instead: Check the timestamp of each backup to understand when changes occurred and pick the right recovery point
✅ Instead: Remember backups are session-scoped and purged when you close the session - use git for permanent version history
❌ Mistake: Not checking available versions before rollback
✅ Instead: Always run
list_history first to see what versions exist and their timestamps before rolling back❌ Mistake: Forgetting backups are only created on write/rename/delete
✅ Instead: If you want a manual snapshot, use
codemap_copy to create an explicit backup with a descriptive name❌ Mistake: Relying on file history as a replacement for version control
✅ Instead: Use file history for session-level recovery and git/version control for permanent project history
❌ Mistake: Not reviewing timestamps when choosing which version to restore
✅ Instead: Check the timestamp of each backup to understand when changes occurred and pick the right recovery point