pi-rewind

Checkpoint/rewind extension for the Pi coding agent. Creates automatic git-based snapshots of your working tree, allowing you to rewind file changes and conversation state when the AI makes mistakes.

Why

Every major coding agent now has rewind/undo: Claude Code (/rewind), Gemini CLI (/rewind), OpenCode (/undo), Cline (Checkpoints). Pi already has community extensions for this — checkpoint-pi and pi-rewind-hook — but neither offers a dedicated /rewind command, diff preview, or a redo stack.

pi-rewind combines the best of both existing extensions with features from the top agents, closing every gap in one package.

Features

• Dedicated /rewind command — checkpoint browser → diff preview → restore
• Esc+Esc keyboard shortcut — quick files-only rewind
• Smart checkpointing — snapshots after write/edit/bash tools, 1 per turn
• Smart dedup — skips checkpoints when worktree unchanged (read-only bash like ls, find, cat don't create checkpoints)
• Descriptive labels — "user prompt" → write → file.ts, edit → other.ts
• Diff preview before restore — see exactly what changes
• Branch labels in picker — [feature] for same-branch, ⚠️ main for cross-branch
• Redo stack (multi-level undo) — "↩ Undo last rewind" in all flows
• Restore options: files + conversation, files only, conversation only
• Safe restore — never deletes node_modules, .venv, or large files
• Branch safety — blocks cross-branch restore (avoids OpenCode bug)
• Smart filtering — excludes 13 dir patterns, files >10MiB, dirs >200 files
• Git-based checkpoints stored as refs (survives restarts)
• Footer status indicator (◆ X checkpoints) with cleanup hint
• Configurable auto-pruning — maxCheckpoints (0=unlimited), keepOldSessions, cleanupHintThreshold
• Cross-session checkpoint picker — two-step (session → checkpoint) when old sessions kept
• /rewind-settings — interactive config menu, auto-saves on change
• /rewind-cleanup — stats + prune options for current and old sessions
• Resume checkpoint on session start
• Fork/tree integration — restore prompts on /fork and /tree navigation
• "Summarize from here" integration (ctx.compact())

Install

# From npm
pi install npm:pi-rewind

# From GitHub
pi install github.com/arpagon/pi-rewind

# For development
git clone git@github.com:arpagon/pi-rewind.git
pi -e ./pi-rewind/src/index.ts

Commands

Command	Behavior
/rewind	Checkpoint browser → diff preview → restore. Two-step cross-session picker when keepOldSessions is true
/rewind-cleanup	Stats overview + prune options (old sessions, current session to max)
/rewind-settings	Interactive settings menu, auto-saves on every change
Esc+Esc	Quick files-only rewind (cross-session aware)

Configuration

Config lives at ~/.pi/agent/config/rewind.json (auto-created on first save). Environment variables override file settings.

{
  "maxCheckpoints": 50,          // 0 = unlimited, never prune current session
  "keepOldSessions": false,       // true = keep checkpoints from previous sessions
  "cleanupHintThreshold": 200     // show cleanup hint when checkpoints exceed this
}

Env var	Overrides
PI_REWIND_MAX_CHECKPOINTS	maxCheckpoints
PI_REWIND_KEEP_OLD_SESSIONS	keepOldSessions (set to 1, true, or yes)
PI_REWIND_CLEANUP_HINT_THRESHOLD	cleanupHintThreshold

Use /rewind-settings to change config live — no restart needed.

Performance

Tested on repos from 20 files to 182K files (87GB monorepo):

Repo	createCheckpoint	loadAll (startup)
Small (20 files)	62ms	8ms
Medium (500 files)	62ms	8ms
Large (5,000 files)	60ms	8ms
Real monorepo (182K files, 87GB)	142ms	8ms

• createCheckpoint = ~60-142ms constant → direct latency added per turn (imperceptible)
• Pi executes extension handlers with await sequentially, so this is the actual overhead
• Old sessions are auto-pruned on startup (525 stale refs → 0 in real-world test)

Run the benchmark yourself: npx tsx tests/bench.ts

Architecture

Two-layer split: core.ts is pure git operations with zero Pi dependency (independently testable), index.ts wires Pi events to core functions.

src/
├── config.ts     #  87 LOC — load/save rewind.json, env var overrides
├── core.ts       # 830 LOC — git operations, filtering, safe restore, branch safety, prune, stats
├── index.ts      # 284 LOC — Pi event hooks, checkpoint scheduling, auto-prune
├── commands.ts   # 741 LOC — /rewind, /rewind-cleanup, /rewind-settings, Esc+Esc, fork/tree
├── state.ts      #  79 LOC — shared mutable state (config preserved across resets)
└── ui.ts         #  49 LOC — footer status, cleanup hint, threshold notifications
tests/
├── core.test.ts  # 362 LOC — 20 tests passing
└── bench.ts      # 252 LOC — performance benchmarks

Development

# Run tests
npx tsx tests/core.test.ts

# Run benchmarks
npx tsx tests/bench.ts

# Test with Pi
pi -e ./src/index.ts

Lineage

This project builds on research and code from:

• checkpoint-pi by prateekmedia — Two-layer architecture, safe restore, smart filtering, unit tests (base)
• pi-rewind-hook by nicobailon — Resume checkpoints, footer status, notifications, auto-pruning (UX inspiration)

And draws feature parity targets from:

• Claude Code /rewind — Summarize from here, double-escape trigger
• Gemini CLI /rewind + /restore — Separate restore commands
• Cline Checkpoints — Per-tool checkpointing, Compare/Restore UI
• OpenCode /undo + /redo — Step-level patches, redo stack

License

MIT