Introduction

In the DeepSeek Harness (DSH) development environment, agents often need to perform complex multi-file refactoring, execute destructive Shell commands, or install dependencies. When an unplanned regression occurs or the workspace state becomes corrupted, manually rolling back with Git is not only cumbersome but also risks losing untracked files or damaging the user’s history.

dsh-time-machine is a DSH plugin designed for such scenarios. It provides a set of intelligent checkpoints, a workspace safety guard, and an instant rollback mechanism, creating lightweight shadow Git snapshots in the background to ensure the integrity and recoverability of workspace state.

Core Features

This plugin provides the following core capabilities:

  • Lightweight shadow Git snapshots: Capture the full workspace, staging area, and untracked files in the background using isolated Git shadow tree references, without interfering with the user’s commit history, current branch, or staging area.
  • Instant safe rollback: Restore either the entire workspace or specific files to any historical checkpoint using non-destructive checkout-index operations, without moving HEAD or rewriting branch history.
  • Visual snapshot diff checker: Provide file-level visual diff comparisons, highlighting added, deleted, and modified lines, and displaying statistics.
  • Interactive sidebar and settings timeline: Integrated into the DSH Web UI sidebar and Settings tab, display session checkpoints as a timeline, and support one-click rollback, diff viewing, and deletion.
  • Automatic recovery on command failure: Automatically record checkpoints when tool or command execution fails to preserve recovery options.
  • Selective file rollback and staging guard: Support single-file restoration, and automatically create checkpoints before high-risk operations to protect the user’s staged Git index.

Installation

Install the plugin using the official command:

dsh plugin --profile web add @goodandready/dsh-time-machine

Configuration

Add the following content to the DSH configuration file to enable automatic snapshots and rollback prompts:

dsh-time-machine:
  autoSnapshotEnabled: true    # Automatically create checkpoints before file changes
  maxSnapshots: 20             # Maximum number of rolling checkpoints retained in memory
  autoHealPrompt: true         # Prompt for rollback when a command fails

Tool Reference

The plugin provides the following tools for Agent use, which can be used for programmatic control:

  • time_machine_checkpoint_create
    • Description: Create a shadow Git workspace checkpoint before performing high-risk edits or operations.
    • Parameters: label?: string, sessionId?: string
  • time_machine_checkpoint_list
    • Description: List recent session checkpoints (in reverse chronological order).
    • Parameters: sessionId?: string
  • time_machine_checkpoint_rollback
    • Description: Restore workspace files to the specified checkpoint.
    • Parameters: id: string, confirm: boolean
  • time_machine_diff
    • Description: Calculate a unified file diff between the current workspace and the target checkpoint.
    • Parameters: from: string, to?: string
  • time_machine_checkpoint_delete
    • Description: Permanently delete a single checkpoint and clear its Git reference.
    • Parameters: id: string, confirm: boolean
  • time_machine_checkpoint_prune
    • Description: Prune session checkpoints, keeping only the latest N entries.
    • Parameters: sessionId?: string, keep?: number

Notes

  • Runtime environment: The plugin runs with the permissions of the current DSH process. Review the source code and license before installation.
  • Dependency requirement: Node.js 20 or higher is required.
  • Version updates:
    • v0.1.16: Security hardening and sidebar label deduplication. Fixed an issue where the sidebar could be registered repeatedly in certain environments, and strictly restricted HTTP methods for REST routes (POST only for modifications, GET for reads).
    • v0.1.15: Selective file rollback and staging guard. Added the single-file restoration tool time_machine_file_rollback and the /rollback-file route.