Preface

The DeepSeek Harness (DSH) agent frequently modifies files or invokes Shell commands (such as sed -i and rm) during execution. Existing rollback plugins often can only capture snapshots at turn boundaries, or only recognize parameters of file-editing tools, and cannot record the side effects produced by Shell commands. This makes it difficult to precisely restore the state before a certain step when an operation goes wrong. dsh-zcode-rewind aims to solve this pain point by providing a fine-grained, tool-call-based checkpoint system.

Plugin Introduction

dsh-zcode-rewind is a workflow plugin for DeepSeek Harness, maintained by BOWLUNA. It provides DSH with per-tool-call workspace checkpoint functionality, capable of capturing every file change and Shell command, storing Blobs using content addressing, and providing line-level diff previews and reversible restore operations.

Core Features

The core capabilities of this plugin include the following:

  1. Full Capture: Captures all mutating tool calls, including bash, pwsh, write, edit, MCP tools, and subagent tools.
  2. Change Logging: Records file deletions, creations, and modifications, and attaches a recoverable previous content hash for each path.
  3. Content Addressing: Stores content-addressed file content using SHA-256, enabling deduplication across sessions and workspaces.
  4. Persistent Log: Provides a persistent change log ordered by entries, which remains available after DSH is restarted.
  5. Operation Support: Supports manually creating checkpoints as well as undo/redo operations.

Installation and Prerequisites

Before installation, ensure the environment meets the following requirements:

  • Node.js >= 20.0.0
  • DSH >= 0.1.5-alpha.1

The installation command is as follows:

dsh plugin --profile web add dsh-zcode-rewind

After installation, DSH must be restarted for the plugin to take effect. You can verify whether the plugin is correctly bound by running dsh --profile web --dump-config | grep workspace-rewind.

Usage

The plugin provides a set of tool commands for managing checkpoints. The main tools and their purposes are as follows:

  • rewind_now: Creates a manual checkpoint, such as before executing a high-risk operation.
  • rewind_list: Lists recent records in reverse chronological order, showing ID, timestamp, tool type, change statistics (+added ~modified -deleted), and sample paths.
  • rewind_diff: Previews the restore plan and line-level unified diff. This operation does not actually modify files.
  • rewind_restore: Executes a restore operation. mode=revert is used to undo a single record; mode=asof is used to restore the workspace to the state of a checkpoint.
  • rewind_undo: Undoes the previous restore operation. Repeated execution toggles the undo/redo state.
  • rewind_status: Displays storage statistics, including record count, Blob count, byte count, quota, and current configuration.

Configuration

The plugin supports adjusting behavior through configuration files. A typical configuration example is as follows:

- insert:
    - id: workspace-rewind
      name: 'dsh-zcode-rewind'
      config:
        capture: all            # 捕获模式：all | fileTools | off
        maxFileBytes: 8388608   # 单文件最大字节数，超过仅记录事件
        maxFiles: 20000         # 单次遍历文件数量上限
        maxTotalBytes: 536870912  # 存储总字节数上限，旧 Blob 会自动清理
        keepRecords: 500        # 日志保留条目数阈值
        excludes: ['.git', 'node_modules', 'dist']
        secretNames: ['.env', '*.pem', '*.key']

Notes

  • Shell Side-Effect Capture: Unlike other rewind plugins on the market, this plugin can capture the side effects of Shell commands (such as sed -i) because it uses fingerprint-based diff comparison rather than parsing arguments.
  • Checkpoint Granularity: Capture is based on “each tool call” rather than “turn boundaries,” enabling more precise problem localization.
  • Storage Location: The storage directory is located at $DSH_HOME/workspace-rewind/, outside the workspace, so it does not pollute the Git repository.
  • Deduplication Mechanism: Because it uses SHA-256 content addressing, identical file content occupies only one copy of storage space across multiple modifications.

Summary

dsh-zcode-rewind provides DeepSeek Harness with fine-grained, reversible workspace state management capabilities. For agent development scenarios that require high reliability and precise control over rollback scope, this plugin is a practical tool. Detailed documentation and source code are available on GitHub.