Timeline & Checkpoints
Relevant source files
The following files were used as context for generating this wiki page:
The Timeline & Checkpoints system in Opcode provides a robust versioning mechanism for Claude Code sessions. It allows users to capture the state of a project at specific moments, visualize the history of a session as a branching tree, and restore or fork from previous states. This ensures that experimental AI-driven code modifications can be safely managed and reverted if necessary.
The system is split between a Rust-based backend that manages file snapshots and compression, and a React-based frontend that provides a visual navigator and diff viewer. Key features include automatic checkpointing based on tool usage, content-addressable storage to minimize disk usage, and the ability to compare changes between different points in time.
Sources: README.md:92-100, src-tauri/src/checkpoint/manager.rs:17-25
Architectural Overview
The architecture follows a client-server model where the frontend interacts with a specialized CheckpointManager on the backend via a set of API endpoints.
Backend Structure (src-tauri)
The backend is responsible for the heavy lifting of state management:
- CheckpointManager: The core orchestrator that tracks file modifications, processes Claude messages for side effects, and triggers snapshots.
- CheckpointStorage: Handles physical persistence, using
zstandard(zstd) for message compression and a content-addressable pool for file snapshots to prevent data duplication. - FileTracker: Maintains an in-memory map of file hashes and modification states to determine which files need to be included in a new checkpoint.
Frontend Structure (src)
The UI components provide the interaction layer:
- TimelineNavigator: A visual tree component that renders the session history and allows users to select, restore, or fork nodes.
- useCheckpoints: A custom React hook that abstracts API calls and manages local state for the timeline UI.
- ClaudeCodeSession: The primary container that integrates the timeline and handles event listeners for auto-checkpointing.
Component Relationship
The following diagram illustrates the relationship between the key components involved in the checkpointing lifecycle:
The diagram shows the flow from the React UI down to the Rust persistence layer.
Sources: src-tauri/src/checkpoint/manager.rs:17-30, src-tauri/src/checkpoint/storage.rs:14-25, src/components/TimelineNavigator.tsx:50-70
Data Models and Schema
The system relies on structured data to represent the session history and individual snapshots.
Core Data Structures
| Structure | Description | Key Fields |
|---|---|---|
| Checkpoint | Metadata for a single saved state. | id, message_index, timestamp, metadata |
| FileSnapshot | A captured version of a single file. | file_path, content, hash, is_deleted |
| TimelineNode | A node in the visual history tree. | checkpoint, children, file_snapshot_ids |
| SessionTimeline | The root container for a session's history. | root_node, current_checkpoint_id, total_checkpoints |
Sources: src/lib/api.ts:162-212
Checkpoint Metadata
Every checkpoint includes a CheckpointMetadata object that summarizes the state at that time:
totalTokens: Cumulative token usage at the time of creation.modelUsed: The specific Claude model that was active.userPrompt: The last prompt sent by the user before the checkpoint.fileChanges: Number of files modified in this specific snapshot.snapshotSize: Estimated size of the compressed data.
Sources: src-tauri/src/checkpoint/manager.rs:188-202, src/lib/api.ts:175-181
Checkpoint Creation Workflow
Checkpoints can be created manually by the user or automatically by the system based on defined strategies.
Creation Logic
When a checkpoint is created, the CheckpointManager performs the following steps:
- File Discovery: Recursively walks the project directory to identify all files.
- Modification Tracking: Uses the
FileTrackerto compare current file hashes against the last known state. - Metadata Extraction: Parses the session message history (JSONL) to extract token counts and the latest prompt.
- Persistence: Saves the compressed message history and unique file snapshots to the content pool.
- Timeline Update: Appends the new node to the
SessionTimelinetree.
This diagram outlines the synchronous flow of creating a new session snapshot.
Sources: src-tauri/src/checkpoint/manager.rs:163-230, src-tauri/src/checkpoint/storage.rs:43-80
Automatic Checkpoint Strategies
Users can configure when the system should automatically save state via CheckpointStrategy:
- Manual: No automatic checkpoints.
- PerPrompt: Creates a checkpoint after every user prompt.
- PerToolUse: Creates a checkpoint whenever Claude executes a tool.
- Smart: Automatically triggers after "destructive" operations like
edit,write, orrm.
Sources: src-tauri/src/checkpoint/manager.rs:500-545, src/lib/api.ts:223-227
Storage and Efficiency
The storage implementation is designed for high performance and low disk footprint.
Content-Addressable Storage (CAS)
Instead of storing full project copies for every checkpoint, CheckpointStorage uses a content-addressable pool. Files are stored using their SHA-256 hash as the filename. If multiple checkpoints reference the same file content, only one physical copy exists on disk.
Sources: src-tauri/src/checkpoint/storage.rs:83-100
Compression
Session message logs are stored as JSONL and compressed using the Zstandard (zstd) algorithm before being written to disk. This significantly reduces the storage requirement for long-running sessions with thousands of messages.
Sources: src-tauri/src/checkpoint/storage.rs:64-68
Navigation and Restoration
The frontend provides a visual interface for interacting with the timeline.
Timeline Tree Rendering
The TimelineNavigator renders the history as a nested tree. It uses the TimelineNode structure where each node contains a list of children, allowing for complex branching if the user forks from a middle point in the session.
Sources: src/components/TimelineNavigator.tsx:185-280
Restore and Fork
- Restore: Replaces the current working directory files with those from the selected checkpoint and truncates the session message history to the corresponding
message_index. - Fork: Creates a new session branch starting from a historical checkpoint, allowing the user to explore a different development path without affecting the original timeline.
The flow for reverting or branching the session state.
Sources: src/components/TimelineNavigator.tsx:120-155, src-tauri/src/checkpoint/manager.rs:445-470
Configuration and Management
Users can manage the lifecycle of checkpoints through settings and automated cleanup.
Checkpoint Settings
The following configuration options are available via api.updateCheckpointSettings:
| Setting | Type | Description |
|---|---|---|
autoCheckpointEnabled | Boolean | Enables or disables automatic snapshots. |
checkpointStrategy | Enum | Determines the trigger for auto-checkpoints. |
keepCount | Number | Number of recent checkpoints to retain before cleanup. |
Sources: src/lib/api.ts:215-227, src-tauri/src/checkpoint/manager.rs:563-577
Garbage Collection
To prevent the content pool from growing indefinitely, the system includes a garbage_collect_content function. This utility scans all file references across all checkpoints and deletes any files in the content_pool that are no longer referenced by any valid checkpoint.
Sources: src-tauri/src/checkpoint/storage.rs:325-365
Conclusion
The Timeline & Checkpoints system is a critical safety feature in Opcode. By combining content-addressable storage with a branching tree visualization, it provides developers with a powerful "undo" mechanism and the ability to manage complex, non-linear AI coding sessions with minimal storage overhead.