In agent development, rolling back file states is often more challenging than backtracking conversation history. When code generation enters deeper waters, developers need a mechanism that saves the current workspace state at each turn boundary so file changes can be rolled back at any time. dsh-tui-checkpoints aims to address this pain point, using a shadow repository mechanism to provide file-level “true backtracking” capability for dsh-TUI.

The following is an introduction to the dsh-tui-checkpoints plugin.

Scope and Features

dsh-tui-checkpoints is a community plugin for dsh-TUI. It does not touch the project’s original .git repository; instead, it creates an independent shadow repository for each workspace.

Core features include:
* Turn snapshots: Automatically saves workspace state at each turn boundary.
* Shadow repository: Maintains independent git repositories under ~/.dsh/checkpoints/repos/.
* File backtracking: Browse and restore file states via the /checkpoints panel.
* Safety mechanism: Automatically creates a safety-* branch before restoration, ensuring the operation can be rolled back.
* Undo capability: Supports rolling back file-level modifications.

Installation and Activation

This plugin is currently in the Spike (technical validation) stage and has not been published to npm. It must be packaged and installed from source.

git clone https://github.com/FUSU123fusu/dsh-tui-checkpoints.git
cd dsh-tui-checkpoints
npm pack
dsh plugin --profile dsh-tui add file:dsh-tui-checkpoints-0.1.0.tgz

After installation, restart dsh-TUI to activate it.

Features and Usage

1. Open the checkpoint panel

Enter the following command in the terminal:

/checkpoints

2. Browse snapshots

The panel list displays snapshot metadata:
* Symbols: ● indicates post-turn snapshots, ◦ indicates pre-turn snapshots.
* Information: Turn number, short Commit hash, timestamp.

3. View differences

Select a row in the list, and the diff statistics between that snapshot and the current workspace are displayed below in real time.

4. Restore file state

Press r to restore. The system requires two confirmations within 3 seconds.
* The restore logic is reset --hard + clean, meaning file contents are restored and newly added files are deleted.
* Before restoration, the current state is first committed to a safety-* branch, making the restore itself reversible.

5. Conversation backtracking

After restoring file state, use the built-in double-press Esc /rewind feature in dsh-TUI to backtrace the conversation to the same turn, keeping file state and conversation state consistent.

Principles and Details

Shadow repository mechanism

The plugin creates a shadow repository at ~/.dsh/checkpoints/repos/<workspace hash>.git. The project directory itself is treated as the work tree for that shadow repository. This means:
* The project’s .git directory is completely unaffected.
* The plugin works even if the project directory is not a git repository.

Snapshot timing

The plugin listens to session/event and performs a snapshot at each occurrence of turn/start (pre-turn) and turn/end (post-turn) in the top-level session. The snapshot operations are queued and executed serially. If there are no file changes, it reuses the HEAD commit to avoid generating many empty commits.

Ignore rules

By default, it excludes directories such as .git and node_modules, reads the project’s .gitignore, and writes the rules into the shadow repository’s info/exclude.

Performance

  • Initial full snapshot: about 5.8s.
  • No-change snapshot: about 0.7s (using add -A + diff --cached).

Nested repository handling

If a workspace contains nested git repositories (submodules or worktrees), the plugin records them as Gitlinks and does not recurse into internal changes.

Notes

  1. Spike stage: This is a technical validation version, not yet published to npm, and the code may be unstable.
  2. File overwrite risk: Restore operations are at the workspace level. If there are currently unsaved edits, restoration directly overwrites them, although those changes have already been safely committed to a safety-* branch.
  3. Separation of conversation and files: Conversation backtracking is handled by the dsh-TUI built-in feature; this plugin only handles file-level state management.

Conclusion

dsh-tui-checkpoints provides file-level backtracking capability for dsh-TUI, solving the pain point of “difficult to roll back code changes” in agent development. Although it is currently a Spike version, its shadow repository design and two-stage restore mechanism (files + conversation) provide a validation foundation for future core PRs.