pi-rewind-hook 1.0.0

package/README.md

@@ -0,0 +1,172 @@
+# Rewind Hook
+
+A Pi agent hook that enables rewinding file changes during coding sessions. Creates automatic checkpoints using git refs, allowing you to restore files to previous states while optionally preserving conversation history.
+
+## Requirements
+
+- Pi agent v0.18.0+
+- Node.js (for installation)
+- Git repository (checkpoints are stored as git refs)
+
+## Installation
+
+```bash
+npx pi-rewind-hook
+```
+
+This will:
+1. Create `~/.pi/agent/hooks/rewind/`
+2. Download the hook files
+3. Add the hook to your `~/.pi/agent/settings.json`
+
+### Alternative Installation
+
+Using curl:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nicobailon/pi-rewind-hook/main/install.js | node
+```
+
+Or clone the repo and configure manually:
+
+```bash
+git clone https://github.com/nicobailon/pi-rewind-hook ~/.pi/agent/hooks/rewind
+```
+
+Then add to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "hooks": ["~/.pi/agent/hooks/rewind/index.ts"]
+}
+```
+
+### Platform Notes
+
+**Windows:** The `npx` command works in PowerShell, Command Prompt, and WSL. If you prefer curl on Windows without WSL:
+
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nicobailon/pi-rewind-hook/main/install.js" -OutFile install.js; node install.js; Remove-Item install.js
+```
+
+## How It Works
+
+### Checkpoints
+
+The hook creates git refs at two points:
+
+1. **Session start** - When pi starts, creates a "resume checkpoint" of the current file state
+2. **Each turn** - Before the agent processes each message, creates a checkpoint
+
+Checkpoints are stored as git refs under `refs/pi-checkpoints/` and are pruned to keep the last 100.
+
+### Rewinding
+
+To rewind:
+
+1. Type `/branch` in pi
+2. Select a message to branch from
+3. Choose a restore option:
+
+**For messages from the current session:**
+
+| Option | Files | Conversation |
+|--------|-------|--------------|
+| **Restore all (files + conversation)** | Restored | Reset to that point |
+| **Conversation only (keep current files)** | Unchanged | Reset to that point |
+| **Code only (restore files, keep conversation)** | Restored | Unchanged |
+
+**For messages from before the current session (uses resume checkpoint):**
+
+| Option | Files | Conversation |
+|--------|-------|--------------|
+| **Restore to session start (files + conversation)** | Restored to session start | Reset to that point |
+| **Conversation only (keep current files)** | Unchanged | Reset to that point |
+| **Restore to session start (files only, keep conversation)** | Restored to session start | Unchanged |
+
+### Resumed Sessions
+
+When you resume a session (`pi --resume`), the hook creates a resume checkpoint. If you branch to a message from before the current session, you can restore files to the state when you resumed (not per-message granularity, but a safety net).
+
+## Examples
+
+### Undo a bad refactor
+
+```
+You: refactor the auth module to use JWT
+Agent: [makes changes you don't like]
+
+You: /branch
+→ Select "refactor the auth module to use JWT"
+→ Select "Code only (restore files, keep conversation)"
+
+Result: Files restored, conversation intact. Try a different approach.
+```
+
+### Start fresh from a checkpoint
+
+```
+You: /branch
+→ Select an earlier message
+→ Select "Restore all (files + conversation)"
+
+Result: Both files and conversation reset to that point.
+```
+
+### Recover after resuming
+
+```bash
+pi --resume  # resume old session
+```
+
+```
+Agent: [immediately breaks something]
+
+You: /branch
+→ Select any old message
+→ Select "Restore to session start (files only, keep conversation)"
+
+Result: Files restored to state when you resumed.
+```
+
+## Viewing Checkpoints
+
+List all checkpoint refs:
+
+```bash
+git for-each-ref refs/pi-checkpoints/
+```
+
+Manually restore to a checkpoint:
+
+```bash
+git checkout refs/pi-checkpoints/checkpoint-1234567890 -- .
+```
+
+Delete all checkpoints:
+
+```bash
+git for-each-ref --format='%(refname)' refs/pi-checkpoints/ | xargs -n1 git update-ref -d
+```
+
+## Uninstalling
+
+1. Remove the hook directory:
+   ```bash
+   rm -rf ~/.pi/agent/hooks/rewind
+   ```
+   On Windows (PowerShell): `Remove-Item -Recurse -Force ~/.pi/agent/hooks/rewind`
+
+2. Remove the hook from `~/.pi/agent/settings.json` (delete the line with `rewind/index.ts` from the `hooks` array)
+
+3. Optionally, clean up git refs in each repo where you used the hook:
+   ```bash
+   git for-each-ref --format='%(refname)' refs/pi-checkpoints/ | xargs -n1 git update-ref -d
+   ```
+
+## Limitations
+
+- Only works in git repositories
+- Checkpoints are per-process (in-memory map), not persisted across restarts
+- Resumed sessions only have a single resume checkpoint for pre-session messages
+- Tracks working directory changes only (not staged/committed changes)

package/index.ts

@@ -0,0 +1,141 @@
+import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+const REF_PREFIX = "refs/pi-checkpoints/";
+const MAX_CHECKPOINTS = 100;
+
+export default function (pi: HookAPI) {
+  const checkpoints = new Map<number, string>();
+  let resumeCheckpoint: string | null = null;
+
+  console.error(`[rewind] Hook loaded`);
+
+  pi.on("session_start", async (event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    const checkpointId = `checkpoint-resume-${Date.now()}`;
+
+    try {
+      await ctx.exec("git", [
+        "update-ref",
+        `${REF_PREFIX}${checkpointId}`,
+        "HEAD",
+      ]);
+
+      resumeCheckpoint = checkpointId;
+      console.error(`[rewind] Created resume checkpoint: ${checkpointId}`);
+    } catch (err) {
+      console.error(`[rewind] Failed to create resume checkpoint: ${err}`);
+    }
+  });
+
+  pi.on("turn_start", async (event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    const checkpointId = `checkpoint-${event.timestamp}`;
+
+    try {
+      await ctx.exec("git", [
+        "update-ref",
+        `${REF_PREFIX}${checkpointId}`,
+        "HEAD",
+      ]);
+
+      checkpoints.set(event.turnIndex, checkpointId);
+      console.error(
+        `[rewind] Created checkpoint ${checkpointId} for turn ${event.turnIndex}`
+      );
+
+      await pruneCheckpoints(ctx);
+    } catch (err) {
+      console.error(`[rewind] Failed to create checkpoint: ${err}`);
+    }
+  });
+
+  pi.on("branch", async (event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    let checkpointId = checkpoints.get(event.targetTurnIndex);
+    let usingResumeCheckpoint = false;
+
+    if (!checkpointId && resumeCheckpoint) {
+      checkpointId = resumeCheckpoint;
+      usingResumeCheckpoint = true;
+    }
+
+    if (!checkpointId) {
+      ctx.ui.notify(
+        "No checkpoint available for this message",
+        "info"
+      );
+      return undefined;
+    }
+
+    const options = usingResumeCheckpoint
+      ? [
+          "Restore to session start (files + conversation)",
+          "Conversation only (keep current files)",
+          "Restore to session start (files only, keep conversation)",
+        ]
+      : [
+          "Restore all (files + conversation)",
+          "Conversation only (keep current files)",
+          "Code only (restore files, keep conversation)",
+        ];
+
+    const choice = await ctx.ui.select("Restore Options", options);
+
+    if (!choice) {
+      ctx.ui.notify("Rewind cancelled", "info");
+      return { skipConversationRestore: true };
+    }
+
+    if (choice.startsWith("Conversation only")) {
+      return undefined;
+    }
+
+    try {
+      const ref = `${REF_PREFIX}${checkpointId}`;
+      await ctx.exec("git", ["checkout", ref, "--", "."]);
+      console.error(`[rewind] Restored files from ${checkpointId}`);
+      ctx.ui.notify(
+        usingResumeCheckpoint 
+          ? "Files restored to session start" 
+          : "Files restored from checkpoint",
+        "success"
+      );
+    } catch (err) {
+      console.error(`[rewind] Failed to restore: ${err}`);
+      ctx.ui.notify(`Failed to restore files: ${err}`, "error");
+      return { skipConversationRestore: true };
+    }
+
+    if (choice.includes("files only") || choice.startsWith("Code only")) {
+      return { skipConversationRestore: true };
+    }
+
+    return undefined;
+  });
+
+  async function pruneCheckpoints(ctx: { exec: (cmd: string, args: string[]) => Promise<{ stdout: string; stderr: string; code: number }> }) {
+    try {
+      const result = await ctx.exec("git", [
+        "for-each-ref",
+        "--sort=creatordate",
+        "--format=%(refname)",
+        REF_PREFIX,
+      ]);
+
+      const refs = result.stdout.trim().split("\n").filter(Boolean);
+
+      if (refs.length > MAX_CHECKPOINTS) {
+        const toDelete = refs.slice(0, refs.length - MAX_CHECKPOINTS);
+        for (const ref of toDelete) {
+          await ctx.exec("git", ["update-ref", "-d", ref]);
+          console.error(`[rewind] Pruned old checkpoint: ${ref}`);
+        }
+      }
+    } catch (err) {
+      console.error(`[rewind] Failed to prune checkpoints: ${err}`);
+    }
+  }
+}

package/install.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const os = require("os");
+
+const REPO_URL = "https://raw.githubusercontent.com/nicobailon/pi-rewind-hook/main";
+const HOOK_DIR = path.join(os.homedir(), ".pi", "agent", "hooks", "rewind");
+const SETTINGS_FILE = path.join(os.homedir(), ".pi", "agent", "settings.json");
+const HOOK_PATH = "~/.pi/agent/hooks/rewind/index.ts";
+
+function download(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      if (res.statusCode === 301 || res.statusCode === 302) {
+        return download(res.headers.location).then(resolve).catch(reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`Failed to download ${url}: ${res.statusCode}`));
+      }
+      let data = "";
+      res.on("data", (chunk) => (data += chunk));
+      res.on("end", () => resolve(data));
+      res.on("error", reject);
+    }).on("error", reject);
+  });
+}
+
+async function main() {
+  console.log("Installing pi-rewind-hook...\n");
+
+  // Create hook directory
+  console.log(`Creating directory: ${HOOK_DIR}`);
+  fs.mkdirSync(HOOK_DIR, { recursive: true });
+
+  // Download hook files
+  console.log("Downloading index.ts...");
+  const hookContent = await download(`${REPO_URL}/index.ts`);
+  fs.writeFileSync(path.join(HOOK_DIR, "index.ts"), hookContent);
+
+  console.log("Downloading README.md...");
+  const readmeContent = await download(`${REPO_URL}/README.md`);
+  fs.writeFileSync(path.join(HOOK_DIR, "README.md"), readmeContent);
+
+  // Update settings.json
+  console.log(`\nUpdating settings: ${SETTINGS_FILE}`);
+  
+  let settings = {};
+  if (fs.existsSync(SETTINGS_FILE)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(SETTINGS_FILE, "utf-8"));
+    } catch (err) {
+      console.error(`Warning: Could not parse existing settings.json: ${err.message}`);
+      console.error("Creating new settings file...");
+    }
+  }
+
+  // Ensure hooks array exists
+  if (!Array.isArray(settings.hooks)) {
+    settings.hooks = [];
+  }
+
+  // Add hook if not already present
+  if (!settings.hooks.includes(HOOK_PATH)) {
+    settings.hooks.push(HOOK_PATH);
+    
+    // Ensure parent directory exists
+    fs.mkdirSync(path.dirname(SETTINGS_FILE), { recursive: true });
+    fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`Added "${HOOK_PATH}" to hooks array`);
+  } else {
+    console.log("Hook already configured in settings.json");
+  }
+
+  console.log("\nInstallation complete!");
+  console.log("\nThe rewind hook will load automatically when you start pi.");
+  console.log("Use /branch to rewind to a previous checkpoint.");
+}
+
+main().catch((err) => {
+  console.error(`\nInstallation failed: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "pi-rewind-hook",
+  "version": "1.0.0",
+  "description": "Rewind hook for Pi agent - automatic git checkpoints with file/conversation restore",
+  "bin": {
+    "pi-rewind-hook": "./install.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicobailon/pi-rewind-hook"
+  },
+  "keywords": [
+    "pi",
+    "pi-agent",
+    "hook",
+    "checkpoint",
+    "rewind",
+    "git"
+  ],
+  "author": "nicobailon",
+  "license": "MIT"
+}