Reasonix Checkpoint and Session Rewind: A Complete Guide to Snapshot-Based Rollbacks

Reasonix provides a git-free, snapshot-based checkpoint system that records the complete state of every file edited during a user turn, enabling deterministic rollback of both code and conversation history through a three-phase rewind workflow.

DeepSeek-Reasonix implements a robust checkpoint and session rewind mechanism that captures immutable snapshots before and after AI-driven mutations. Unlike traditional version control, this system operates entirely within session-specific directories, storing JSON metadata and content-addressed blobs that allow you to restore your workspace to any prior turn without touching your repository’s git history.

How Reasonix Checkpoints Work

The checkpoint architecture is built around snapshot isolation and automatic mutation tracking. Every time a tool modifies a file, the system captures the pre-edit state, executes the change, then records the post-edit state—creating a complete audit trail in a single JSON file.

Snapshot Storage Architecture

Checkpoints persist as individual JSON files inside a session-specific directory named <session>.ckpt/. According to the source code in internal/checkpoint/checkpoint.go lines 40‑65, the Store struct manages this directory alongside a content-addressed BlobStore for large file payloads.

Each checkpoint file contains:

• Turn metadata: The turn number, ISO timestamp, and prompt that generated the edit.
• FileSnap entries: Defined in lines 33‑46, these capture the pre-edit content, file mode, SHA‑256 fingerprint, and capture source (e.g., previewer, before-mutation, after-mutation).
• Coverage data: Indicates which files were successfully captured and flags any gaps in the snapshot.

This design is intentionally git-free—it lives alongside session data and never modifies your working repository, making it safe for experimental changes.

Automatic Capture via MutationObserver

The MutationObserver interface intercepts tool-generated edits to populate checkpoints automatically. In internal/checkpoint/observer.go lines 196‑234, the observer invokes CaptureBefore prior to mutation and CaptureAfter once the edit completes, ensuring every change is recorded without manual intervention.

The Session Rewind Workflow

A rewind operation restores your workspace and/or conversation to the state saved in a specific checkpoint. The controller implements this as a deterministic three-phase process: Prepare, Apply, and Persist.

Step 1: Prepare the Rewind Plan

Before executing any changes, Controller.PrepareRewind(turn, scope) validates that the requested checkpoint exists and that the session is in a valid state. As implemented in internal/control/rewind.go lines 95‑129, this method:

1. Verifies no turn is currently running.
2. Checks that the conversation boundary is still present (not compacted).
3. Returns a RewindPlan struct containing an OK boolean and any DisabledReason if the operation cannot proceed.

The scope parameter accepts "code", "conversation", or "both" (default), determining which aspects of the session will be restored.

Step 2: Apply Code and Conversation Changes

Once prepared, Controller.Rewind(turn, scope) executes the restoration. This method, exposed via the HTTP endpoint POST /rewind registered in internal/serve/serve.go line 408, invokes specialized appliers:

• Code restoration: The checkpoint store restores each file to its captured pre-edit content using SHA‑256 verification, or deletes the file if it did not exist at that checkpoint.
• Conversation truncation: conversationApplier.ApplyConversationTruncate (lines 34‑56) removes all messages after the checkpoint’s MsgIndex. If the conversation was compacted past this index, the operation fails with "conversation rewind unavailable".

Step 3: Persist the New State

After successful restoration, the controller writes a new session snapshot so subsequent operations see the rewound state. The checkpoint store updates its internal turn counter and boundary map, making the rewound position the new "head" of the session history. The system also supports undo-rewind, which reverses the most recent rewind transaction if it remains available in the store.

Practical Implementation Examples

Rewind via HTTP API

Trigger a rewind through the Reasonix server using the POST /rewind endpoint defined in internal/serve/serve.go lines 25‑46:

POST https://<reasonix-server>/rewind
Content-Type: application/json

{
  "turn": 3,
  "scope": "both"
}

The server returns 204 No Content on success or 500 with an error message if the checkpoint is unavailable or the conversation was compacted.

List Available Checkpoints

Retrieve checkpoint metadata for UI selection via the endpoint implemented at line 1072:

GET https://<reasonix-server>/checkpoints

Response format:

[
  {
    "Turn": 1,
    "Time": "2024-08-05T12:34:56Z",
    "Prompt": "Add new utils",
    "Paths": ["utils.go"],
    "CanUndoFiles": true,
    "Legacy": false
  }
]

Programmatic Rewind in Go

Use the controller directly for server-side automation:

import (
    "reasonix/internal/control"
    "reasonix/internal/checkpoint"
)

func rewindToTurn(ctl *control.Controller, turn int) error {
    // Validate and obtain execution plan
    plan, err := ctl.PrepareRewind(turn, control.RewindBoth)
    if err != nil {
        return fmt.Errorf("cannot prepare rewind: %w", err)
    }
    if !plan.OK {
        return fmt.Errorf("rewind disabled: %s", plan.DisabledReason)
    }

    // Execute the rewind
    if err := ctl.Rewind(turn, control.RewindBoth); err != nil {
        return fmt.Errorf("rewind failed: %w", err)
    }
    return nil
}

Manual Checkpoint Creation

While the MutationObserver handles this automatically, you can manually capture checkpoints using the store API:

import "reasonix/internal/checkpoint"

func captureManualCheckpoint(store *checkpoint.Store, turn int, prompt string) error {
    cp := &checkpoint.Checkpoint{
        Turn:     turn,
        Time:     time.Now(),
        Prompt:   prompt,
        MsgIndex: currentMessageCount,
    }
    
    // Capture pre-mutation state
    store.CaptureBefore("/path/to/file.go", checkpoint.CaptureBeforeOpts{
        Source: checkpoint.CaptureBeforeMutation,
    })
    
    // ... perform file mutation ...
    
    // Capture post-mutation state
    store.CaptureAfter("/path/to/file.go", checkpoint.CaptureAfterOpts{
        Seq:    1,
        Source: checkpoint.CaptureAfterMutation,
    })
    
    return store.Finalize(cp)
}

Summary

Reasonix checkpoint and session rewind functionality provides a reliable safety net for AI-assisted programming:

• Git-free snapshots stored in <session>.ckpt/ directories capture complete file states including SHA‑256 fingerprints and capture sources.
• Automatic instrumentation via MutationObserver ensures every tool-generated edit is recorded without manual overhead.
• Three-phase rewind process (Prepare, Apply, Persist) enables safe restoration of code, conversation, or both via Controller.PrepareRewind and Controller.Rewind.
• HTTP API surface exposes /rewind and /checkpoints endpoints for desktop and CLI integration.
• Deterministic boundaries prevent rewinding past compacted conversation history, ensuring data consistency.

Frequently Asked Questions

Where are Reasonix checkpoints physically stored?

Checkpoints are stored as JSON files in a session-specific directory named <session>.ckpt/, created and managed by the Store struct in internal/checkpoint/checkpoint.go. Large file payloads are stored in a content-addressed BlobStore to deduplicate repeated content across snapshots.

Can I rewind only the code without affecting the conversation history?

Yes. The scope parameter in both PrepareRewind and the HTTP API accepts "code", "conversation", or "both". Passing "code" restores the file system to the checkpoint state while preserving all conversation messages after that turn, allowing you to revert changes without losing dialogue context.

What happens if I try to rewind to a checkpoint but the conversation was compacted?

The rewind operation will fail with the error "conversation rewind unavailable". As implemented in internal/control/rewind.go, the ApplyConversationTruncate method validates that the checkpoint’s MsgIndex still exists in the event log. If compaction removed those messages, the boundary is lost and conversation rewind is disabled, though code-only rewind may still succeed.

How is this different from using git to revert changes?

Unlike git, Reasonix checkpoints capture pre-edit states before mutations occur, not just diffs. The system is also fully automated—MutationObserver hooks in internal/checkpoint/observer.go capture every tool action without requiring commits. Additionally, checkpoints include conversation state via MsgIndex, allowing you to rewind the dialogue itself, something impossible with git alone.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}