$ cat ~/map/pi-rewind-hook.md
pi-rewind-hook
Pi extension that records file-state rewind points so /tree navigation, fork, and resume can restore exact file snapshots alongside the conversation.
extensions✓ Oct 16
Facts
- repository
- github.com/nicobailon/pi-rewind-hook ↗
- GitHub Stars
- ★ 167
- Forks
- 16
- license
- —
- npm / mo
- —
- last push
- Sep 28, 2026
install
pi install npm:pi-rewind-hook## TL;DR
Pi extension that records exact file-state rewind points as hidden session entries, restorable during /tree navigation and across forked and resumed sessions — snapshots are git commits kept reachable under a single ref.
## Key points
- $Records exact file-state rewind points and offers restoration during /fork and /tree navigation and across resumed and forked sessions; metadata lives in the session itself as hidden entries, so rewind history survives forks, resumes, tree navigation, and compaction.
- $Snapshot commits are kept reachable through one repo-local ref (refs/pi-rewind/store) instead of one ref per checkpoint, with the session ledger authoritative; identical worktree tree SHAs deduplicate to the existing snapshot commit.
- $/fork offers conversation-only (keep files), restore all (files plus conversation), code only (restore files, keep conversation), and undo-last-file-rewind options; /tree offers keep current files, restore files to that point, and undo last file rewind.
- $Restores the exact state of tracked files and untracked, non-ignored files without staging the real git index; ignored files, empty directories, and toolResult or bashExecution nodes are out of scope, and it only works inside git repositories.
- $Rewind points resolve across session lineage via parentSession links; v2 reads only session-native rewind-turn and rewind-op metadata, not legacy checkpoint refs.
- $Optional retention in ~/.pi/agent/settings.json caps unpinned snapshots (maxSnapshots, maxAgeDays), pins labeled entries, and offers scanMode and startupBudgetMs; without retention, exact history is kept indefinitely.
- $Works with pi-custom-compaction: exact checkpoints can bind to custom compaction markers so /tree offers restore directly on them — optional, since default compaction checkpoints work without the companion.
## FAQ
Q What does it need to run?
Pi agent v0.74.0 or later, Node.js for installation, and a git repository — Rewind only works in git repos and stores snapshots as git commits.
Q What happens with no retention settings?
Exact history is kept with no automatic expiration, which can grow git object storage without bound over time; configure rewind.retention with maxSnapshots and maxAgeDays to prune, optionally pinning labeled entries.
Q Does it work with custom compaction setups?
Yes — with pi-custom-compaction installed, Rewind can bind an exact checkpoint to a background-summary marker's own session-tree node; without it, pi's default compaction and Rewind's native compaction checkpoints continue to work.
## References
## Related entries
$ pi-better-rewind-redo
Rewind files and conversation together from an earlier message, with multi-level redo and recovery from interrupted restores.
$ pi-duo
Two persistent, resumable peer agents — Austin implements up front, Tony verifies behind — sharing each other's live session context.
$ CCompactor
Turns finished coding-agent sessions — Pi, Claude Code, Codex — into compact, verified, provenance-linked handoff artifacts, in TypeScript.
Last updated: Aug 31, 2026