Checkpoint Manager Backend

Relevant source files

The following files were used as context for generating this wiki page:

• src-tauri/src/checkpoint/manager.rs
• src-tauri/src/checkpoint/storage.rs
• src-tauri/src/checkpoint/state.rs
• src-tauri/src/commands/claude.rs
• src/lib/api.ts

The Checkpoint Manager Backend is a robust system within Opcode designed to manage session versioning, file state tracking, and state restoration for Claude Code sessions. It enables developers to create snapshots of their project's state at specific points in time, allowing for non-linear exploration of code changes through branching timelines and instant restoration.

This backend system handles the heavy lifting of calculating file hashes, managing content-addressable storage to minimize disk usage, and maintaining a tree-based session timeline. It provides the logic for both manual and automated checkpointing strategies, such as creating snapshots after destructive tool operations or per user prompt.

Sources: src-tauri/src/checkpoint/manager.rs, src-tauri/src/checkpoint/storage.rs

Core Architecture

The backend is organized into three primary layers: the state management layer, the operational manager, and the persistent storage layer.

Component Relationship

The following diagram illustrates how the different backend components interact to manage session state.

The CheckpointState acts as a global container in the Tauri application, managing the lifecycle of CheckpointManager instances for every active session. Each manager utilizes a FileTracker to monitor modifications and a CheckpointStorage instance to handle physical I/O and compression.

Sources: src-tauri/src/checkpoint/state.rs:11-20, src-tauri/src/checkpoint/manager.rs:16-25

Key Backend Components

1. CheckpointState

The CheckpointState is a thread-safe registry that ensures only one manager exists per session. It uses an Arc<RwLock<HashMap<...>>> to allow concurrent access across various Tauri commands.

• get_or_create_manager: Retrieves an existing manager or initializes a new one using the session and project IDs.
• remove_manager: Cleans up resources when a session ends.

Sources: src-tauri/src/checkpoint/state.rs:43-74

2. CheckpointManager

The CheckpointManager orchestrates the logic for tracking session data and generating snapshots.

• Message Tracking: It intercepts JSONL messages from the Claude process to detect tool usage (like edit or bash) and automatically trigger file tracking.
• Heuristic File Tracking: It monitors specific bash commands (e.g., rm, mv, sed) to flag tracked files as potentially modified.
• Metadata Extraction: It parses messages to calculate token usage (input, output, and cache tokens) and identify the model used for each checkpoint.

Sources: src-tauri/src/checkpoint/manager.rs:56-125, src-tauri/src/checkpoint/manager.rs:260-315

3. CheckpointStorage

The storage layer implements content-addressable storage (CAS) and Zstd compression to optimize performance.

• Content Pool: Files are stored by their SHA-256 hash. Identical file versions across different checkpoints reference the same physical file in the content_pool directory.
• Reference System: Each checkpoint maintains a refs directory containing JSON metadata for every file in that snapshot, linking the relative project path to a hash in the pool.
• Timeline Persistence: The tree structure of the session is saved as a JSON timeline, supporting parent-child relationships for branching.

Sources: src-tauri/src/checkpoint/storage.rs:75-115, src-tauri/src/checkpoint/storage.rs:335-375

Data Models

The system uses specific structures to represent the state of a session and its history.

Structure	Description	Key Fields
Checkpoint	A single snapshot in time.	id, session_id, parent_checkpoint_id, timestamp, metadata
FileSnapshot	State of a file at a checkpoint.	file_path, content, hash, is_deleted, permissions
CheckpointMetadata	Statistics for a checkpoint.	total_tokens, model_used, user_prompt, file_changes
SessionTimeline	The full tree of a session.	root_node, current_checkpoint_id, checkpoint_strategy

Sources: src/lib/api.ts:167-217, src-tauri/src/checkpoint/manager.rs:18-25

Core Workflows

Checkpoint Creation Flow

When a checkpoint is created, the system performs a recursive scan of the project and updates the timeline.

During creation, the system ensures every file in the project (excluding hidden directories like .git) is tracked to ensure the snapshot represents the complete project state.

Sources: src-tauri/src/checkpoint/manager.rs:142-205, src-tauri/src/checkpoint/storage.rs:43-70

Restoration Workflow

Restoring a checkpoint is a destructive operation that synchronizes the current project directory with the snapshot.

1. Project Scan: Collects all files currently existing in the project.
2. Deletion: Removes any files present in the current project that do not exist in the target checkpoint.
3. Restoration: Writes content from the storage pool to the project path and restores original Unix permissions (if applicable).
4. Timeline Update: Updates the current_checkpoint_id and resets the FileTracker state.

Sources: src-tauri/src/checkpoint/manager.rs:355-430

Automation Strategies

The backend supports several strategies for automatic checkpoint creation defined in the CheckpointStrategy enum:

Strategy	Trigger Logic
Manual	No automatic checkpoints; user must trigger manually.
PerPrompt	Triggers a checkpoint after every user message detected in the message stream.
PerToolUse	Triggers a checkpoint whenever a tool_use message type is detected.
Smart	Triggers only after "destructive" tools: write, edit, multiedit, bash, rm, or delete.

Sources: src-tauri/src/checkpoint/manager.rs:510-565, src/lib/api.ts:223-227

API Endpoints (Tauri Commands)

The backend exposes several functions to the frontend via Tauri's IPC mechanism.

Command	File	Description
create_checkpoint	claude.rs	Manually creates a snapshot with an optional description.
restore_checkpoint	claude.rs	Reverts the project and session history to a specific ID.
list_checkpoints	claude.rs	Returns a flat list of all checkpoints in the session.
get_session_timeline	claude.rs	Returns the hierarchical tree structure of the session.
get_checkpoint_diff	claude.rs	Calculates additions/deletions between two checkpoints.
cleanup_old_checkpoints	claude.rs	Deletes old snapshots and runs garbage collection on orphaned files.

Sources: src-tauri/src/commands/claude.rs:945-1215

Conclusion

The Checkpoint Manager Backend provides a sophisticated version control layer specifically tuned for AI coding sessions. By combining content-addressable storage, message-based heuristics, and automated strategies, it allows Opcode to offer a "time-travel" experience that protects the developer's codebase during complex AI-driven refactors.

Sources: src-tauri/src/checkpoint/manager.rs, src-tauri/src/checkpoint/storage.rs