pi-tree-undo

中文文档见 README.zh_CN.md

A Pi extension for file undo/redo driven by session tree navigation. No slash commands needed — moving backward and forward in /tree automatically reverts or re-applies file changes.

  open /tree
      │
      ▼
  ├── earlier node ◀── select & Enter = undo (files restored to that state)
  │
  └── later node   ◀── select & Enter = redo (files restored to that state)

Features

• Navigation is undo/redo: in /tree, moving backward undoes, moving forward redoes. Branch crossing is handled automatically (abandoned branch undone, target branch applied).

• Multi-step rewind: jump back several nodes at once — every file change from every traversed turn is undone.

• Change widget: after navigating, a widget above the editor shows what happened to each file, including added/removed line counts:

  1 file(s) changed
  Modified:
    /path/src/a.ts (+12 -3)          ← +added lines -removed lines
  Added:
    /path/new.ts
  Deleted:
    /path/old.ts
  

• External-edit protection: if a file was modified outside the extension, its current content is first backed up to <path>.pi-undo-conflict-<timestamp>, then overwritten with the target state. The backup path is flagged in the widget (warning color).

• Per-session isolation: each session keeps its own snapshot store.

Installation

Requires pi.

Try it without installing

pi -e ./src/index.ts

Install as a package (then just run pi)

pnpm install
pnpm build          # compile to dist/
pi install ./       # register with pi

Uninstall: pi uninstall ./

Quick start

1. Start pi with the extension loaded and confirm the File undo ready notice.
2. Have the model edit files (via write / edit).
3. Type /tree to open the session tree, move with the arrow keys, press Enter:
   • pick an earlier node → undo that change
   • pick a later node → redo
4. The widget above the editor shows each file's change (what changed, how many lines added/removed).
5. Navigate to any node to inspect that state; navigate back downstream to return to the present.

Typical use cases

1. Revert a bad change

The model modified the wrong thing. Open /tree, select the node before the change, press Enter — the file is restored. Select the later node again to redo; you can change your mind at any point.

2. Find which turn introduced a problem

After several turns something broke. Step backward one node at a time and watch the widget to identify the exact turn, then stop at the node just before it.

3. Switch between branches

Fork two approaches from a node and edit files differently on each branch. Use /tree to flip between branches — the extension undoes the current branch's changes and applies the target branch's, so the workspace follows.

4. Rewind multiple turns at once

When undoing several turns, the widget shows the precise net change from the current state to the target state (a line edited in multiple turns counts once), e.g. (+5 -2) means the file gained 5 lines and lost 2 overall.

How it works (brief)

• Every completed turn records a snapshot for each file modified via edit/write (a unified diff; before stores the full old content).
• Snapshots live in ~/.pi/agent/sessions/<project>/<sessionId>.undo-snapshots.json and follow the session.
• On navigation the extension finds the common ancestor of old and new nodes, undoes the abandoned segment, and applies the target segment.
• Before applying, the on-disk content is checked against the snapshot; mismatches are backed up then overwritten, so manual edits are never silently lost.

Limitations

• Only edit / write are tracked: files changed via bash (e.g. echo >> file) are not recorded and cannot be undone.
• Deletions are not directly reversible: pi has no dedicated delete tool, so removals typically go through bash rm and are out of scope; a file previously created by write can be resurrected on redo because its creation snapshot still exists.
• Manually edited files are backed up before overwrite — check the backup file if you need the old content back.

Development

pnpm dev          # load the extension in pi: pi -e ./src/index.ts
pnpm typecheck    # tsc --noEmit
pnpm test         # run tests
pnpm build        # compile to dist/

Detailed development notes live in AGENTS.md.