better-pi-rewind

Claude Code-style file checkpoints for pi and OMP.

The extension records the state of files changed through the host's built-in edit and write tools. Rewinding can restore those files, reset descendant Git commits or an amended checkpoint commit, navigate the current conversation to an earlier user prompt, or combine those actions.

Install

Install the published package from npm.

Pi

pi install npm:better-pi-rewind

OMP

omp plugin install better-pi-rewind

Both hosts can also install a tagged GitHub release directly:

pi install git:github.com/raine/better-pi-rewind@v0.2.0
omp plugin install github:raine/better-pi-rewind#v0.2.0

Use

Run /rewind and select the point before an earlier user prompt. The extension then offers:

• Restore code and conversation
• Restore conversation only
• Restore code only
• Restore code with a hard reset of commits created after the checkpoint
• Restore code and roll back an immediately amended checkpoint commit

Git rollback choices appear when the selected checkpoint and the current state use the same repository and branch. Descendant commits can be reset when the checkpoint commit is an ancestor of HEAD. An amended commit can be rolled back when the HEAD reflog shows that it immediately replaced the checkpoint commit. The extension describes the detected change and asks for confirmation before running git reset --hard.

/checkpoint is an alias for /rewind.

Double Escape

Press Escape twice within 500 ms with an empty editor. The extension opens its rewind selector with every user prompt, the code changes that would be restored, and a current-position marker. The same selector is available through /rewind.

Disable the host's built-in double-Escape action so the extension owns this interaction.

For Pi, set this in ~/.pi/agent/settings.json:

{
  "doubleEscapeAction": "none"
}

For OMP, run:

omp config set doubleEscapeAction none

While an assistant response is active, Escape retains the host's normal single-press cancellation behavior. Selecting an earlier prompt opens the restore action menu.

Configuration

Create better-pi-rewind.json in the host's agent directory for user-wide settings. For Pi this is normally ~/.pi/agent/better-pi-rewind.json; for OMP it is normally ~/.omp/agent/better-pi-rewind.json.

{
  "activeRunEscapePresses": 1,
  "escapeWindowMs": 500
}

activeRunEscapePresses accepts 1 or 2. Set it to 2 to guard against accidental interruption by requiring two presses. escapeWindowMs accepts an integer from 50 to 5000 and controls both active cancellation and idle rewind detection. The defaults are 1 press and 500 ms.

A trusted project can override either setting in .pi/better-pi-rewind.json for Pi or .omp/better-pi-rewind.json for OMP. Project settings take precedence over user settings. Run /reload after editing a configuration file.

How checkpoints work

1. When an assistant response starts for a user prompt, the extension snapshots every file already under checkpoint tracking.
2. Before the first edit or write call touches another file, the extension copies its current contents into that prompt's checkpoint.
3. A missing file is represented explicitly, allowing rewind to remove files created by write.
4. Each checkpoint records the Git repository root, branch, and HEAD commit when the working directory belongs to a repository with at least one commit.
5. Checkpoint metadata is stored as custom entries in the host's session JSONL. It follows the conversation tree when the host navigates or resumes a session.
6. Backup files live under the active host's agent directory: ~/.pi/agent/file-history/<session-id>/ for Pi and ~/.omp/agent/file-history/<session-id>/ for OMP. Host profiles and agent directory overrides change the parent directory along with other host data.
7. Restore compares existence, mode, size, and content before writing. Matching files stay untouched, changed files are copied from the backup, and their permissions are restored.

File-only restore actions leave Git references and the index unchanged. Commit reset actions hard-reset the current branch to the checkpoint's HEAD before restoring checkpointed files. This order lets checkpointed file contents recover states that differed from the checkpoint commit.

Coverage

Checkpoint coverage consists of files changed through the host's built-in edit and write tools. Arbitrary shell commands, custom tools, and external editor changes do not register new files. Once a path enters tracking, each later user prompt captures its current state regardless of how it changed.

Restoration is best-effort per file. A failure is reported while restoration of other tracked files continues. Git reset, code restoration, and conversation navigation run sequentially rather than transactionally.

A commit reset overwrites the working tree and index through git reset --hard, which may also overwrite untracked files. The extension reapplies checkpointed files afterward, but changes outside checkpoint coverage are not recoverable through the extension. Git's reflog and ORIG_HEAD provide the standard Git recovery paths for the removed commits.

Development

Load a checkout while developing the extension:

pi install /absolute/path/to/better-pi-rewind
omp plugin link /absolute/path/to/better-pi-rewind

Try the checkout for one run without installing it:

pi -e /absolute/path/to/better-pi-rewind
omp -e /absolute/path/to/better-pi-rewind/extensions/rewind.ts

Install dependencies and run the checks:

npm install
npm run check

The implementation follows the shared Pi extension surface and adapts host-specific conversation branching. Useful upstream references include:

• git-checkpoint.ts
• Pi extension API source
• OMP extension API source
• OMP legacy Pi compatibility loader
• Pi package documentation

Unlike pi-rewind, better-pi-rewind uses per-file backups and tracks file creation and permissions without requiring a Git repository.

License

MIT