pi-diff

Prompt-cycle workspace diff sidebar for pi.

pi-diff snapshots files lazily as tools mutate them, then shows the net prompt-cycle changes in a right-hand sidebar. write and edit are tracked per file just before they run. Broader mutators like bash use a session-wide full-workspace baseline that is refreshed from post-tool scans, so repeated broad mutations reuse the previous scan instead of forcing another pre-tool snapshot. It is designed to feel native to pi: full-height, keyboard navigable, theme-aware, and rendered with pi's built-in diff renderer.

Features

• tracks prompt-cycle file deltas without a full workspace scan on every prompt
• captures edit and write changes per file, then reuses post-scan workspace baselines for later broad mutators like bash or unknown custom tools
• auto-opens when a prompt cycle changes files
• selectable prompt-cycle and git diff tabs in the sidebar
• optional worker-thread live polling for the git diff tab, plus manual refresh
• git diff state construction now runs in the worker so the main extension thread only applies updates
• the worker caches per-file fingerprints and reuses unchanged file diffs across refreshes
• inline diff viewer with line numbers and pi-native fragment highlighting for true single-line replacements
• deleted and binary-file changes supported
• remembers the last diff in session state
• built-in self-test command for viewer regression checks

Install

Before first publish, replace the placeholder package/repository fields in package.json:

• @your-npm-username/pi-diff
• kyerpotts/pi-diff

Then users can install with:

pi install npm:@your-npm-username/pi-diff

Or try it without installing globally:

pi -e npm:@your-npm-username/pi-diff

Commands and shortcuts

• Ctrl+. — toggle the sidebar; opening also focuses it
• Ctrl+H / Ctrl+L — move focus between the editor and diff sidebar while the sidebar is visible
• Ctrl+Alt+D — toggle the sidebar
• /diff-sidebar — toggle the sidebar
• /diff-sidebar-focus — focus/unfocus the sidebar
• /diff-sidebar-view prompt|git — switch the sidebar to the prompt-cycle or git diff tab
• /diff-sidebar-refresh — refresh the git diff tab immediately
• /diff-sidebar-live-poll on|off|toggle — control live polling for the git diff tab
• /diff-sidebar-selftest — load a synthetic diff cycle for regression testing the viewer

When focused:

• 1 or P — switch to the prompt-cycle tab
• 2 or G — switch to the git diff tab
• R — refresh the git diff tab immediately
• A — toggle git diff live polling on/off
• Tab or ←/→ — switch between file list and inline viewer
• file list: ↑↓, PgUp, PgDn, Home, End
• inline viewer: ↑↓, PgUp, PgDn, Home, End
• Ctrl+H — return focus to the editor
• Ctrl+. — hide the sidebar
• Esc — unfocus the sidebar

Package layout

• extensions/pi-diff/ — publishable extension source
• .pi/extensions/pi-diff/index.ts — local development shim so /reload still works in this repo
• sample markdown/text files in the repo root — local fixtures for interactive testing, not included in the npm package

Local development

Use the local shim for hot reload in this repo:

/reload

If you also have pi-diff installed as a pi package, the repo-local shim defers to the installed package to avoid duplicate shortcut registration. For local extension development, remove or disable the installed package first, or temporarily force the shim with PI_DIFF_USE_LOCAL_EXTENSION=1.

Or launch pi directly against the publishable extension entry point:

pi -e ./extensions/pi-diff/index.ts -p "test"

Run the built-in viewer regression fixture:

/diff-sidebar-selftest

Publish to npm

This repo is scaffolded for tag-based npm publishing via GitHub Actions.

1. Create an npm account.
2. Replace the placeholder package name in package.json with your real scope, typically:
   • @your-npm-username/pi-diff
3. Create a GitHub repository named pi-diff and push this repo there.
4. In the GitHub repo settings, add a repository secret:
   • NPM_TOKEN — an npm automation token with publish access
5. Bump package.json version.
6. Push a matching git tag:

git tag v0.1.0
git push origin main --tags

The publish workflow verifies that the tag matches package.json and then runs:

npm publish --access public --provenance

Workflows

• .github/workflows/ci.yml — validates package metadata and runs npm pack --dry-run
• .github/workflows/publish.yml — publishes to npm on version tags like v0.1.0

License

Apache-2.0

Limitations

• .git/ is skipped during prompt-cycle snapshotting
• the first broad workspace mutator in a session can establish the session baseline instead of producing a diff if no full baseline exists yet
• external file mutations that happen outside pi tools are best-effort rather than guaranteed
• the git diff tab compares HEAD to the current working tree, excludes untracked files, and can live-poll while visible from a worker thread that also builds the git diff state off the main thread with per-file diff reuse
• binary files show synthetic placeholder lines rather than textual diffs
• very large text diffs may fall back to an approximate mode to avoid excessive memory use