pi-better-rewind-redo

---

A third-party Pi extension powered by filesnap. Pick an earlier message, preview the file changes, and restore the files and conversation together. Use /redo to return to where you were.

Snapshots live outside your workspace. No Git repository is required, and snapshots do not modify your Git history or index.

Table of Contents

• Quick Start
• Commands
• Sessions
• File Coverage
• Recovery
• Settings
• Development

---

Quick Start

Requires Node.js 22.19+ and Pi. Developed against @earendil-works/pi-coding-agent 0.85.1; tested on Linux x64. Other platforms have not been tested with this extension.

Install through Pi’s package manager:

pi install npm:pi-better-rewind-redo

Start pi in your project. If Pi is already running, restart it to load the extension. For local development, run npm ci && pi install . from this repository instead; keep that directory in place.

The official filesnap CLI is installed automatically as an npm dependency. No Rust toolchain, global filesnap installation, or environment configuration is required. Keep optional dependencies enabled so npm can install the platform binary.

Then work as usual:

1. Ask Pi to make a change.
2. Run /rewind, select an earlier message, and confirm the file preview.
3. Run /redo to restore the state before that rewind.

Update or remove

pi update npm:pi-better-rewind-redo
pi remove npm:pi-better-rewind-redo

Add -l to the install command for a project-local installation. To follow the repository instead of npm releases, install with pi install git:github.com/extracurricular-ai/pi-better-rewind-redo.

---

Commands

Command	Description
/rewind	Select a user message, preview writes and deletions, and restore files and conversation to before that message
/redo	Restore files and conversation to before the last rewind; repeat for multiple levels
/rewind-status	Show checkpoints, redo history, recovery status, and storage location
/rewind-recover	Retry recovery after an interrupted or failed restore

The current version restores files and conversation together. Previews show file paths and operations. Line-by-line diffs, separate file/conversation restore modes, and double-Escape shortcuts are not implemented.

Sessions

A checkpoint is created when each user message starts, including messages added while Pi is working. After a rewind, the original message text returns to the editor. Reattach images or other attachments before resending.

Sending a new message clears redo history. The original conversation branch remains in Pi's session tree. Rewind and redo history persist in saved sessions.

Pi's /tree and /fork navigate the conversation only. Using them creates a new checkpoint boundary and clears this extension's redo history without restoring files. Use /rewind and /redo for combined file and conversation navigation.

File Coverage

filesnap combines three sources of paths:

Source	Coverage
Git index	Indexed paths in the workspace, including their uncommitted contents. Git history and index are left untouched.
Pi edit and write	Saves file contents before the actual write, including hidden files and files outside the workspace. Declared paths remain watched for 99 further turns after their last declaration by default.
Recent files	Adds up to 100 recent files, at most 16 MiB each. Skips hidden directories and common dependency/build directories. These limits apply to this scan, not to declared files.

A failed preimage capture blocks the corresponding edit or write. The tools retain Pi's native argument handling, path resolution, rendering, and write queue.

Text and binary contents can be captured. Changes made by Bash, MCP tools, other extensions, or external programs are recoverable only when the affected paths were captured before the change. There is no general write interception for those tools. A new file created after a checkpoint and never declared is not guaranteed to be deleted by rewind.

.filesnapignore applies to captures, declarations, and restores. Excluded files are not protected. Changing ignore rules changes restore coverage, including for existing snapshots.

The extension supports local regular files. Its edit wrappers reject symbolic links, hard links, and non-regular files. It does not restore directory structure or all file metadata, and does not support remote file backends such as SSH. Avoid enabling another extension that replaces the same edit or write tools.

Recovery

Before restoring, the extension saves a rescue snapshot and shows the planned changes. After confirmation it checks the workspace and ignore rules again; if either changed during the preview, the operation is cancelled. A multi-step restore uses the same confirmed ignore rules throughout.

The recovery journal is saved before files change. Files are restored first, then the conversation. If file restoration fails or conversation navigation is cancelled, the extension tries to restore the previous state. If recovery also fails, it retains the journal and snapshots and blocks further editing until /rewind-recover succeeds.

Rescue snapshots can be restored repeatedly. After a process interruption, reopen the same saved session and run /rewind-recover. Sessions started with --no-session cannot preserve a recovery journal across process exits.

Restores are not atomic across files and conversations, and there is no workspace lock across processes. Pause other agents, editors, and background writers while restoring. Session-tree navigation is blocked while restoration or recovery is pending.

Snapshot storage is not automatically pruned. Snapshots may contain sensitive file contents. End the relevant sessions and make sure their rewind, redo, and recovery points are no longer needed before deleting stored data.

Settings

No settings are required. These environment variables are optional:

Variable	Description
FILESNAP_BIN	Override the bundled dependency with a native CLI executable, for development or debugging. On Windows use filesnap.exe, not an npm .cmd wrapper. Required CLI capabilities are checked before the first operation.
FILESNAP_DATA_DIR	Snapshot data root; must be an absolute path outside the workspace. Defaults to $XDG_DATA_HOME or ~/.local/share; on Windows, %LOCALAPPDATA%.

The default CLI is filesnap@0.5.0, resolved from the extension's own dependencies rather than the workspace or PATH.

Development

npm ci
npm run check
npm test

# Load the extension for one run
pi -e ./src/index.ts

Tests use the real npm CLI, Pi session manager, and native file tools without model API calls. They cover file coverage, repeated writes, multi-level redo, session restart, unchanged Git state, ignore rules, preview invalidation, navigation cancellation, restore failures, and recovery. Installation checks also exercise an empty PATH and a package installed with production dependencies only.

Licensed under Apache-2.0.