respawn-session 0.0.1 → 0.0.2

package/README.md

@@ -19,7 +19,7 @@ gh auth status
 
 ## Usage
 
-Initialize local storage and install a Claude Code Stop hook:
+Initialize local storage and install autosave Stop hooks for Claude Code and Codex:
 
 ```sh
 respawn init
@@ -31,59 +31,37 @@ Save the current active agent session from inside a git worktree:
 respawn save
 ```
 
-Resume the latest saved session for a branch:
-
-```sh
-respawn angela/fix-bugs
-```
-
-List saved sessions:
-
-```sh
-respawn list
-```
-
-## Publishing
-
-Before publishing, confirm the local runtime and GitHub CLI auth are ready:
+Autosave is what the installed hooks run. It skips unchanged transcripts so repeated Stop events do not create duplicate gists:
 
 ```sh
-bun --version
-gh auth status
+respawn autosave
 ```
 
-Run npm's packaging checks first:
+Resume the latest saved session for a branch:
 
 ```sh
-npm pack --dry-run
-npm publish --dry-run
+respawn angela/fix-bugs
 ```
 
-Publish the package:
+Attach the latest saved session to the current GitHub PR:
 
 ```sh
-npm publish
+respawn tag
 ```
 
-If npm returns a 403 saying two-factor authentication is required, publish with a current OTP code:
+Resume from a tagged PR, even if the branch was deleted:
 
 ```sh
-npm publish --otp <your-current-2fa-code>
+respawn 123
+respawn https://github.com/org/repo/pull/123
 ```
 
-After publish, users can install the CLI globally:
+List saved sessions:
 
 ```sh
-npm install -g respawn-session
 respawn list
 ```
 
-One-off `npx` usage can download the package, but the bin still uses `#!/usr/bin/env bun`, so Bun must be installed:
-
-```sh
-npx respawn-session list
-```
-
 ## How It Works
 
 `respawn save` detects the active agent in this order:
@@ -107,6 +85,8 @@ The local index lives at:
 
 Branches can have multiple saved sessions. `respawn <branch>` restores the newest `savedAt` entry for the current repo and branch. `respawn list` shows every saved entry so older sessions remain discoverable.
 
+`respawn tag` writes a hidden metadata comment to the current PR. The comment stores session pointers, not the transcript body. Transcripts still live in your private gists. This lets `respawn <pr-url|number>` recover the newest tagged session after a branch is merged or deleted.
+
 ## Agent Paths
 
 Claude Code transcripts are restored to:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "respawn-session",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Save and resume Claude Code or Codex agent sessions by git branch.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -1,24 +1,37 @@
 #!/usr/bin/env bun
 import { initRespawn } from "./commands/init";
 import { listSessions } from "./commands/list";
-import { resumeSession } from "./commands/resume";
+import { resumePrSession, resumeSession } from "./commands/resume";
 import { saveSession } from "./commands/save";
+import { tagCurrentPr } from "./commands/tag";
 
 export type Route =
   | { name: "help" }
   | { name: "save" }
+  | { name: "autosave" }
   | { name: "list" }
   | { name: "init" }
-  | { name: "resume"; branch: string };
+  | { name: "tag" }
+  | { name: "resume"; branch: string }
+  | { name: "resume-pr"; prRef: string };
 
 export function route(args: string[]): Route {
   const [command] = args;
   if (!command || command === "help" || command === "--help" || command === "-h") {
     return { name: "help" };
   }
-  if (command === "save" || command === "list" || command === "init") {
+  if (
+    command === "save" ||
+    command === "autosave" ||
+    command === "list" ||
+    command === "init" ||
+    command === "tag"
+  ) {
     return { name: command };
   }
+  if (isPrRef(command)) {
+    return { name: "resume-pr", prRef: command };
+  }
   return { name: "resume", branch: command };
 }
 
@@ -32,6 +45,10 @@ export async function main(args = Bun.argv.slice(2)): Promise<void> {
     console.log((await saveSession()).message);
     return;
   }
+  if (selected.name === "autosave") {
+    console.log((await saveSession({ mode: "autosave" })).message);
+    return;
+  }
   if (selected.name === "list") {
     console.log((await listSessions()) || "No saved sessions");
     return;
@@ -40,8 +57,15 @@ export async function main(args = Bun.argv.slice(2)): Promise<void> {
     console.log(await initRespawn());
     return;
   }
+  if (selected.name === "tag") {
+    console.log((await tagCurrentPr()).message);
+    return;
+  }
 
-  const result = await resumeSession(selected.branch);
+  const result =
+    selected.name === "resume-pr"
+      ? await resumePrSession(selected.prRef)
+      : await resumeSession(selected.branch);
   const [cmd, ...cmdArgs] = result.command;
   const proc = Bun.spawn([cmd, ...cmdArgs], {
     stdin: "inherit",
@@ -55,12 +79,19 @@ function helpText(): string {
   return [
     "Usage:",
     "  respawn save",
+    "  respawn autosave",
+    "  respawn tag",
     "  respawn <branch>",
+    "  respawn <pr-url|number>",
     "  respawn list",
     "  respawn init",
   ].join("\n");
 }
 
+function isPrRef(value: string): boolean {
+  return /^\d+$/.test(value) || /github\.com\/[^/]+\/[^/]+\/pull\/\d+/.test(value);
+}
+
 if (import.meta.main) {
   main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));

package/src/commands/init.ts

@@ -22,10 +22,27 @@ export async function initRespawn(deps: InitDeps = {}): Promise<string> {
   const indexPath = deps.indexPath ?? defaultIndexPath(home);
   await writeIndex(indexPath, await readIndex(indexPath));
 
-  const settingsPath = join(home, ".claude", "settings.json");
-  const settings = await readSettings(settingsPath);
+  const command = "respawn autosave || true";
+  const claudePath = join(home, ".claude", "settings.json");
+  const codexPath = join(home, ".codex", "hooks.json");
+  await installStopHook(claudePath, command);
+  await installStopHook(codexPath, command);
+
+  return `Initialized respawn index at ${indexPath} and autosave Stop hooks at ${claudePath} and ${codexPath}`;
+}
+
+async function readSettings(path: string): Promise<ClaudeSettings> {
+  try {
+    return JSON.parse(await readFile(path, "utf8")) as ClaudeSettings;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+async function installStopHook(path: string, command: string): Promise<void> {
+  const settings = await readSettings(path);
   const stopHooks = settings.hooks?.Stop ?? [];
-  const command = "respawn save || true";
   const alreadyInstalled = stopHooks.some((group) =>
     group.hooks?.some((hook) => hook.command === command),
   );
@@ -35,19 +52,9 @@ export async function initRespawn(deps: InitDeps = {}): Promise<string> {
       matcher: "",
       hooks: [{ type: "command", command }],
     });
-    settings.hooks = { ...settings.hooks, Stop: stopHooks };
-    await mkdir(dirname(settingsPath), { recursive: true });
-    await writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
   }
 
-  return `Initialized respawn index at ${indexPath} and Claude Stop hook at ${settingsPath}`;
-}
-
-async function readSettings(path: string): Promise<ClaudeSettings> {
-  try {
-    return JSON.parse(await readFile(path, "utf8")) as ClaudeSettings;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
-    throw error;
-  }
+  settings.hooks = { ...settings.hooks, Stop: stopHooks };
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`);
 }

package/src/commands/resume.ts

@@ -2,6 +2,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { resumeCmd, targetTranscriptPath } from "../agents";
 import { checkoutBranch, currentRepo } from "../git";
+import { checkoutPr, getRespawnTag } from "../github";
 import {
   defaultIndexPath,
   findLatestSession,
@@ -17,6 +18,14 @@ export type ResumeDeps = {
   targetTranscriptPath?: typeof targetTranscriptPath;
 };
 
+export type ResumePrDeps = {
+  currentRepo?: typeof currentRepo;
+  getRespawnTag?: typeof getRespawnTag;
+  downloadGist?: typeof downloadGist;
+  checkoutPr?: typeof checkoutPr;
+  targetTranscriptPath?: typeof targetTranscriptPath;
+};
+
 export async function resumeSession(
   branch: string,
   deps: ResumeDeps = {},
@@ -46,3 +55,37 @@ export async function resumeSession(
     session,
   };
 }
+
+export async function resumePrSession(
+  prRef: string,
+  deps: ResumePrDeps = {},
+): Promise<{
+  command: string[];
+  path: string;
+  session: SavedSession;
+}> {
+  const repo = await (deps.currentRepo ?? currentRepo)();
+  const tag = await (deps.getRespawnTag ?? getRespawnTag)(prRef);
+  if (!tag || tag.repo !== repo) {
+    throw new Error(`No respawn PR tag found for ${repo}#${prRef}`);
+  }
+
+  const session = [...tag.sessions]
+    .sort((a, b) => a.savedAt.localeCompare(b.savedAt))
+    .at(-1);
+  if (!session) {
+    throw new Error(`Respawn PR tag for ${repo}#${prRef} has no sessions`);
+  }
+
+  const transcript = await (deps.downloadGist ?? downloadGist)(session.gistUrl);
+  const path = (deps.targetTranscriptPath ?? targetTranscriptPath)(session);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, transcript);
+  await (deps.checkoutPr ?? checkoutPr)(prRef);
+
+  return {
+    command: resumeCmd(session.agent, session.sessionId),
+    path,
+    session,
+  };
+}

package/src/commands/save.ts

@@ -1,7 +1,10 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { locateActiveTranscript } from "../agents";
 import { currentBranch, currentRepo, currentSha } from "../git";
 import {
   defaultIndexPath,
+  readIndex,
   recordSession,
   type SavedSession,
 } from "../index-file";
@@ -9,6 +12,7 @@ import { createGist } from "../storage/gist";
 
 export type SaveDeps = {
   indexPath?: string;
+  mode?: "save" | "autosave";
   locateActiveTranscript?: typeof locateActiveTranscript;
   currentRepo?: typeof currentRepo;
   currentBranch?: typeof currentBranch;
@@ -19,6 +23,7 @@ export type SaveDeps = {
 
 export async function saveSession(deps: SaveDeps = {}): Promise<{
   message: string;
+  saved: boolean;
   session: SavedSession;
 }> {
   const locate = deps.locateActiveTranscript ?? locateActiveTranscript;
@@ -32,6 +37,37 @@ export async function saveSession(deps: SaveDeps = {}): Promise<{
   const repo = await (deps.currentRepo ?? currentRepo)();
   const branch = await (deps.currentBranch ?? currentBranch)();
   const sha = await (deps.currentSha ?? currentSha)();
+  const indexPath = deps.indexPath ?? defaultIndexPath();
+  const transcriptHash = await hashFile(transcript.path);
+
+  if (deps.mode === "autosave") {
+    const index = await readIndex(indexPath);
+    const unchanged = index.sessions.some(
+      (session) =>
+        session.repo === repo &&
+        session.branch === branch &&
+        session.agent === transcript.agent &&
+        session.sessionId === transcript.sessionId &&
+        session.transcriptHash === transcriptHash,
+    );
+    if (unchanged) {
+      return {
+        message: `No transcript changes to autosave for ${branch}`,
+        saved: false,
+        session: [...index.sessions]
+          .reverse()
+          .find(
+            (session) =>
+              session.repo === repo &&
+              session.branch === branch &&
+              session.agent === transcript.agent &&
+              session.sessionId === transcript.sessionId &&
+              session.transcriptHash === transcriptHash,
+          )!,
+      };
+    }
+  }
+
   const gistUrl = await (deps.createGist ?? createGist)(
     transcript.path,
     `respawn: ${repo}@${branch}`,
@@ -46,11 +82,17 @@ export async function saveSession(deps: SaveDeps = {}): Promise<{
     agent: transcript.agent,
     savedAt: (deps.now ?? (() => new Date()))().toISOString(),
     relativePath: transcript.relativePath,
+    transcriptHash,
   };
 
-  await recordSession(deps.indexPath ?? defaultIndexPath(), session);
+  await recordSession(indexPath, session);
   return {
-    message: `Saved ${session.agent} session ${session.sessionId} for ${branch}`,
+    message: `${deps.mode === "autosave" ? "Autosaved" : "Saved"} ${session.agent} session ${session.sessionId} for ${branch}`,
+    saved: true,
     session,
   };
 }
+
+async function hashFile(path: string): Promise<string> {
+  return createHash("sha256").update(await readFile(path)).digest("hex");
+}

package/src/commands/tag.ts

@@ -0,0 +1,44 @@
+import {
+  currentPr,
+  getRespawnTag,
+  parseGitHubRepo,
+  upsertRespawnComment,
+} from "../github";
+import type { RespawnPrTag } from "../github";
+import { saveSession } from "./save";
+
+export type TagDeps = {
+  saveSession?: typeof saveSession;
+  currentPr?: typeof currentPr;
+  getRespawnTag?: typeof getRespawnTag;
+  upsertRespawnComment?: typeof upsertRespawnComment;
+};
+
+export async function tagCurrentPr(deps: TagDeps = {}): Promise<{
+  message: string;
+  tag: RespawnPrTag;
+}> {
+  const saved = await (deps.saveSession ?? saveSession)();
+  const pr = await (deps.currentPr ?? currentPr)();
+  const repo = parseGitHubRepo(saved.session.repo);
+  const existing = await (deps.getRespawnTag ?? getRespawnTag)(String(pr.number));
+  const tag: RespawnPrTag = {
+    version: 1,
+    repo: saved.session.repo,
+    pr: pr.number,
+    branch: saved.session.branch,
+    sessions: [...(existing?.sessions ?? []), saved.session],
+  };
+
+  await (deps.upsertRespawnComment ?? upsertRespawnComment)({
+    owner: repo.owner,
+    name: repo.name,
+    pr: pr.number,
+    tag,
+  });
+
+  return {
+    message: `Tagged PR #${pr.number} with ${saved.session.agent} session ${saved.session.sessionId}`,
+    tag,
+  };
+}

package/src/github.ts

@@ -0,0 +1,133 @@
+import type { SavedSession } from "./index-file";
+import { runCommand, type RunCommand } from "./shell";
+
+const markerStart = "<!-- respawn-session";
+const markerEnd = "-->";
+
+export type GitHubRepo = {
+  owner: string;
+  name: string;
+};
+
+export type PrInfo = {
+  number: number;
+  url: string;
+  headRefName: string;
+};
+
+export type RespawnPrTag = {
+  version: 1;
+  repo: string;
+  pr: number;
+  branch: string;
+  sessions: SavedSession[];
+};
+
+type GhComment = {
+  id?: string;
+  body?: string;
+};
+
+export function parseGitHubRepo(remote: string): GitHubRepo {
+  const trimmed = remote.trim();
+  const ssh = trimmed.match(/^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/);
+  if (ssh) return { owner: ssh[1], name: ssh[2] };
+
+  const https = trimmed.match(/^https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/);
+  if (https) return { owner: https[1], name: https[2] };
+
+  throw new Error(`Unsupported GitHub remote: ${remote}`);
+}
+
+export function encodeRespawnComment(tag: RespawnPrTag): string {
+  return `${markerStart}\n${JSON.stringify(tag, null, 2)}\n${markerEnd}`;
+}
+
+export function decodeRespawnComment(body: string): RespawnPrTag | null {
+  const start = body.indexOf(markerStart);
+  if (start === -1) return null;
+  const jsonStart = start + markerStart.length;
+  const end = body.indexOf(markerEnd, jsonStart);
+  if (end === -1) return null;
+
+  try {
+    const parsed = JSON.parse(body.slice(jsonStart, end).trim()) as RespawnPrTag;
+    return parsed.version === 1 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function currentPr(run: RunCommand = runCommand): Promise<PrInfo> {
+  const raw = await run("gh", [
+    "pr",
+    "view",
+    "--json",
+    "number,url,headRefName",
+  ]);
+  const parsed = JSON.parse(raw) as PrInfo;
+  return parsed;
+}
+
+export async function getRespawnTag(
+  prRef: string,
+  run: RunCommand = runCommand,
+): Promise<RespawnPrTag | null> {
+  const raw = await run("gh", ["pr", "view", prRef, "--json", "comments"]);
+  const parsed = JSON.parse(raw) as { comments?: GhComment[] };
+  return findRespawnComment(parsed.comments ?? [])?.tag ?? null;
+}
+
+export async function upsertRespawnComment(
+  input: {
+    owner: string;
+    name: string;
+    pr: number;
+    tag: RespawnPrTag;
+  },
+  run: RunCommand = runCommand,
+): Promise<RespawnPrTag> {
+  const raw = await run("gh", [
+    "pr",
+    "view",
+    String(input.pr),
+    "--json",
+    "comments",
+  ]);
+  const parsed = JSON.parse(raw) as { comments?: GhComment[] };
+  const existing = findRespawnComment(parsed.comments ?? []);
+  const body = encodeRespawnComment(input.tag);
+
+  if (existing?.id) {
+    await run("gh", [
+      "api",
+      `repos/${input.owner}/${input.name}/issues/comments/${existing.id}`,
+      "-X",
+      "PATCH",
+      "-f",
+      `body=${body}`,
+    ]);
+  } else {
+    await run("gh", ["pr", "comment", String(input.pr), "--body", body]);
+  }
+
+  return input.tag;
+}
+
+export async function checkoutPr(
+  prRef: string,
+  run: RunCommand = runCommand,
+): Promise<void> {
+  await run("gh", ["pr", "checkout", prRef]);
+}
+
+function findRespawnComment(
+  comments: GhComment[],
+): { id?: string; tag: RespawnPrTag } | null {
+  for (const comment of comments) {
+    if (!comment.body) continue;
+    const tag = decodeRespawnComment(comment.body);
+    if (tag) return { id: comment.id, tag };
+  }
+  return null;
+}

package/src/index-file.ts

@@ -13,6 +13,7 @@ export type SavedSession = {
   agent: AgentName;
   savedAt: string;
   relativePath?: string;
+  transcriptHash?: string;
 };
 
 export type RespawnIndex = {