codemap_rollback

Restore a file from session backup history to instantly recover from mistakes

backuprecoveryrollbackundorestore

Parameters

Name	Type	Required	Description
`filePath`	`string`	✅ Required	File path to restore from backup
`version`	`number`	❌ Optional	Backup version to restore (defaults to latest)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_rollback",
  "arguments": {
    "filePath": "src/auth.ts"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "message": "File restored from backup version 3",
  "filePath": "src/auth.ts",
  "version": 3,
  "timestamp": "2026-04-11T12:30:45.123Z",
  "reason": "write"
}

ℹ️When to Use This Tool

codemap_rollback

Instantly recover from a corrupted or broken file edit
Undo experimental changes that didn't work out
Restore files after a batch operation went wrong
Recover from accidental syntax errors or broken template literals
Go back to a working state when refactoring introduces bugs

💡Common Patterns

Instant Recovery Pattern

1. Make changes that break something
2. codemap_rollback({ filePath: 'file.ts' })
3. File instantly restored to working state

The fastest way to undo mistakes - no git commands, no manual file restoration.

Test-Driven Rollback Pattern

1. Make risky changes
2. Run tests
3. If tests fail: codemap_rollback({ filePath: 'file.ts' })
4. If tests pass: commit changes

Automatically rollback when tests fail to maintain a working codebase.

Version Selection Pattern

1. codemap_list_history({ filePath: 'file.ts' })
2. Review versions and timestamps
3. codemap_rollback({ filePath: 'file.ts', version: N })

Choose the exact recovery point when you need to go back multiple versions.

💡Pro Tips

Automatic backups: CodeMap creates backups automatically before write/rename/delete - you don't need to manually create them
Session-scoped: Backups are purged when you close the session - use git for permanent version history
Latest is default: Omit version parameter to restore the most recent backup
Instant recovery: Rollback is immediate - no need for manual file copying or git operations
Not a git replacement: Use rollback for session-level recovery and git for permanent project history

✅Best Practices

Check available versions with list_history before rolling back to specific versions
Test immediately after rollback to verify the restored state is actually correct
Document why you rolled back in commit messages or team communication
Use rollback for quick recovery during active development sessions
Combine with git for comprehensive version control (rollback for session, git for permanence)
Don't rely exclusively on rollback - commit good work to git regularly

⚠️Common Mistakes

❌ Mistake: Assuming backups persist across sessions
✅ Instead: Remember session-scoped backups are purged on codemap_close - use git for permanent history

❌ Mistake: Rolling back without checking what version you're restoring
✅ Instead: Run list_history first to see timestamps and choose the right recovery point

❌ Mistake: Using rollback as a replacement for version control
✅ Instead: Use rollback for immediate session recovery and git for project-wide version management

❌ Mistake: Rolling back and immediately making the same mistake again
✅ Instead: After rollback, identify what went wrong before making new changes

❌ Mistake: Not testing the file after rollback
✅ Instead: Verify the restored file works correctly - older versions might have their own issues

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_backup_list-history

codemap_io_write

codemap_io_copy