respawn-session 0.0.2 → 0.0.5

package/README.md

@@ -17,56 +17,133 @@ bun --version
 gh auth status
 ```
 
-## Usage
+## Quick Start
 
-Initialize local storage and install autosave Stop hooks for Claude Code and Codex:
+Initialize once on each machine. This creates `~/.respawn/index.json` and installs autosave Stop hooks for Claude Code and Codex:
 
 ```sh
 respawn init
 ```
 
-Save the current active agent session from inside a git worktree:
+Work normally in Claude Code or Codex. `respawn init` makes sessions autosave when the agent stops. To save immediately from inside an active agent session, run:
 
 ```sh
 respawn save
 ```
 
-Autosave is what the installed hooks run. It skips unchanged transcripts so repeated Stop events do not create duplicate gists:
+Resume the latest saved session for a branch:
 
 ```sh
-respawn autosave
+respawn angela/fix-bugs
 ```
 
-Resume the latest saved session for a branch:
+Resume from a PR that was tagged with `respawn tag`:
+
+```sh
+respawn 123
+respawn https://github.com/org/repo/pull/123
+```
+
+## Common Workflows
+
+### Manual Branch Save
+
+Inside an active Claude Code or Codex session:
+
+```sh
+respawn save
+```
+
+Later, from a clone or worktree for the same repo:
+
+```sh
+respawn <branch>
+```
+
+Example:
 
 ```sh
 respawn angela/fix-bugs
 ```
 
-Attach the latest saved session to the current GitHub PR:
+### Autosave
+
+Run this once per machine:
+
+```sh
+respawn init
+```
+
+After that, Claude Code and Codex Stop hooks run:
+
+```sh
+respawn autosave
+```
+
+Autosave hashes the transcript and skips unchanged sessions, so repeated Stop events do not create duplicate gists.
+
+### PR Tagging
+
+Use this when you want a session to survive branch deletion after merge:
 
 ```sh
 respawn tag
 ```
 
-Resume from a tagged PR, even if the branch was deleted:
+That writes or updates a hidden metadata comment on the current GitHub PR. The comment stores session pointers, not the transcript body. Transcripts still live in your private gists.
+
+Later, resume from the PR:
 
 ```sh
 respawn 123
 respawn https://github.com/org/repo/pull/123
 ```
 
-List saved sessions:
+### List Saved Sessions
+
+Show every saved session in your local index:
 
 ```sh
 respawn list
 ```
 
+### Import Existing Sessions
+
+Backfill sessions that already exist on this machine:
+
+```sh
+respawn import
+```
+
+Import scans Claude Code and Codex transcripts, groups them by their recorded cwd, and saves sessions whose cwd is still an available git worktree. It skips transcripts that are already in `~/.respawn/index.json` and skips deleted or non-git worktrees.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `respawn init` | Creates the local index and installs autosave hooks |
+| `respawn save` | Saves the active Claude Code or Codex transcript |
+| `respawn autosave` | Saves only if the transcript changed |
+| `respawn tag` | Saves and attaches session metadata to the current PR |
+| `respawn import` | Backfills existing local Claude Code and Codex sessions |
+| `respawn <branch>` | Restores the newest session for a branch |
+| `respawn <pr-number>` | Restores the newest session from a tagged PR |
+| `respawn <pr-url>` | Restores the newest session from a tagged PR URL |
+| `respawn list` | Lists locally indexed sessions |
+| `respawn version` | Prints the installed CLI version |
+| `respawn update` | Updates the global npm install to the latest release |
+
+If your installed version does not recognize `respawn update`, bootstrap once with:
+
+```sh
+npm install -g respawn-session@latest
+```
+
 ## How It Works
 
 `respawn save` detects the active agent in this order:
 
-1. Claude Code via `CLAUDE_SESSION_ID`
+1. Claude Code via `CLAUDE_SESSION_ID`, then `~/.claude/sessions/*.json`
 2. Codex via `CODEX_TUI_SESSION_LOG_PATH`, `CODEX_SESSION_ID`, or the newest `~/.codex/sessions/**.jsonl` transcript for the current cwd
 
 It then runs:

package/package.json

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

package/src/agents/claude.ts

@@ -1,10 +1,10 @@
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import type { LocatedTranscript, LocateOptions } from "./types";
+import type { ImportableTranscript, LocatedTranscript, LocateOptions } from "./types";
 
 export function encodeClaudeProjectPath(cwd: string): string {
-  return cwd.replaceAll("/", "-");
+  return cwd.replace(/[^A-Za-z0-9._-]/g, "-");
 }
 
 export function transcriptPath(
@@ -27,14 +27,86 @@ export function locateTranscript(
 ): LocatedTranscript | null {
   const env = options.env ?? process.env;
   const sessionId = env.CLAUDE_SESSION_ID;
-  if (!sessionId) return null;
+  if (sessionId) {
+    const path = transcriptPath(sessionId, options);
+    if (existsSync(path)) return { agent: "claude", path, sessionId };
+  }
 
-  const path = transcriptPath(sessionId, options);
-  if (!existsSync(path)) return null;
-
-  return { agent: "claude", path, sessionId };
+  return locateFromSessionRegistry(options);
 }
 
 export function resumeCmd(sessionId: string): string[] {
   return ["claude", "--resume", sessionId];
 }
+
+export function listTranscripts(options: LocateOptions = {}): ImportableTranscript[] {
+  const home = options.home ?? homedir();
+  const sessionsDir = join(home, ".claude", "sessions");
+  if (!existsSync(sessionsDir)) return [];
+
+  return readdirSync(sessionsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => readSessionRecord(join(sessionsDir, entry.name)))
+    .filter(
+      (record): record is Required<Pick<ClaudeSessionRecord, "sessionId" | "cwd">> &
+        ClaudeSessionRecord => Boolean(record?.sessionId && record.cwd),
+    )
+    .map((record): ImportableTranscript | null => {
+      const path = transcriptPath(record.sessionId, {
+        ...options,
+        cwd: record.cwd,
+      });
+      if (!existsSync(path)) return null;
+      return {
+        agent: "claude" as const,
+        path,
+        sessionId: record.sessionId,
+        cwd: record.cwd,
+        savedAt: record.updatedAt
+          ? new Date(record.updatedAt).toISOString()
+          : undefined,
+      };
+    })
+    .filter((transcript): transcript is ImportableTranscript => transcript !== null);
+}
+
+type ClaudeSessionRecord = {
+  sessionId?: string;
+  cwd?: string;
+  updatedAt?: number;
+};
+
+function locateFromSessionRegistry(
+  options: LocateOptions = {},
+): LocatedTranscript | null {
+  const cwd = options.cwd ?? process.cwd();
+  const home = options.home ?? homedir();
+  const sessionsDir = join(home, ".claude", "sessions");
+  if (!existsSync(sessionsDir)) return null;
+
+  const records = readdirSync(sessionsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => readSessionRecord(join(sessionsDir, entry.name)))
+    .filter(
+      (record): record is Required<Pick<ClaudeSessionRecord, "sessionId" | "cwd">> &
+        ClaudeSessionRecord => Boolean(record?.sessionId && record.cwd === cwd),
+    )
+    .sort((a, b) => (a.updatedAt ?? 0) - (b.updatedAt ?? 0));
+
+  for (const record of records.reverse()) {
+    const path = transcriptPath(record.sessionId, options);
+    if (existsSync(path)) {
+      return { agent: "claude", path, sessionId: record.sessionId };
+    }
+  }
+
+  return null;
+}
+
+function readSessionRecord(path: string): ClaudeSessionRecord | null {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as ClaudeSessionRecord;
+  } catch {
+    return null;
+  }
+}

package/src/agents/codex.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, relative } from "node:path";
-import type { LocatedTranscript, LocateOptions } from "./types";
+import type { ImportableTranscript, LocatedTranscript, LocateOptions } from "./types";
 
 const uuidPattern =
   /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
@@ -54,6 +54,30 @@ export function resumeCmd(sessionId: string): string[] {
   return ["codex", "resume", sessionId];
 }
 
+export function listTranscripts(options: LocateOptions = {}): ImportableTranscript[] {
+  const home = options.home ?? homedir();
+  const sessionsDir = codexSessionsDir(home);
+  if (!existsSync(sessionsDir)) return [];
+
+  return walkJsonl(sessionsDir)
+    .map((path): ImportableTranscript | null => {
+      const meta = readCodexMeta(path);
+      const sessionId = meta?.id ?? sessionIdFromCodexPath(path);
+      if (!sessionId || !meta?.cwd) return null;
+
+      const rel = relative(sessionsDir, path);
+      return {
+        agent: "codex" as const,
+        path,
+        sessionId,
+        cwd: meta.cwd,
+        relativePath: rel.startsWith("..") ? undefined : rel,
+        savedAt: statSync(path).mtime.toISOString(),
+      };
+    })
+    .filter((transcript): transcript is ImportableTranscript => transcript !== null);
+}
+
 function locatedFromPath(
   path: string,
   cwd: string,

package/src/agents/index.ts

@@ -1,4 +1,5 @@
 import type { LocatedTranscript, LocateOptions } from "./types";
+import type { ImportableTranscript } from "./types";
 import * as claude from "./claude";
 import * as codex from "./codex";
 
@@ -11,6 +12,10 @@ export function locateActiveTranscript(
   );
 }
 
+export function listAllTranscripts(options: LocateOptions = {}): ImportableTranscript[] {
+  return [...claude.listTranscripts(options), ...codex.listTranscripts(options)];
+}
+
 export function resumeCmd(agent: LocatedTranscript["agent"], sessionId: string): string[] {
   if (agent === "claude") return claude.resumeCmd(sessionId);
   return codex.resumeCmd(sessionId);

package/src/agents/types.ts

@@ -7,6 +7,11 @@ export type LocatedTranscript = {
   relativePath?: string;
 };
 
+export type ImportableTranscript = LocatedTranscript & {
+  cwd: string;
+  savedAt?: string;
+};
+
 export type LocateOptions = {
   cwd?: string;
   home?: string;

package/src/cli.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env bun
 import { initRespawn } from "./commands/init";
+import { importSessions } from "./commands/import";
 import { listSessions } from "./commands/list";
 import { resumePrSession, resumeSession } from "./commands/resume";
 import { saveSession } from "./commands/save";
 import { tagCurrentPr } from "./commands/tag";
+import { updateRespawn, versionText } from "./commands/update";
 
 export type Route =
   | { name: "help" }
@@ -11,7 +13,10 @@ export type Route =
   | { name: "autosave" }
   | { name: "list" }
   | { name: "init" }
+  | { name: "import" }
   | { name: "tag" }
+  | { name: "version" }
+  | { name: "update" }
   | { name: "resume"; branch: string }
   | { name: "resume-pr"; prRef: string };
 
@@ -20,12 +25,17 @@ export function route(args: string[]): Route {
   if (!command || command === "help" || command === "--help" || command === "-h") {
     return { name: "help" };
   }
+  if (command === "version" || command === "--version" || command === "-v") {
+    return { name: "version" };
+  }
   if (
     command === "save" ||
     command === "autosave" ||
     command === "list" ||
     command === "init" ||
-    command === "tag"
+    command === "import" ||
+    command === "tag" ||
+    command === "update"
   ) {
     return { name: command };
   }
@@ -57,10 +67,22 @@ export async function main(args = Bun.argv.slice(2)): Promise<void> {
     console.log(await initRespawn());
     return;
   }
+  if (selected.name === "import") {
+    console.log((await importSessions()).message);
+    return;
+  }
   if (selected.name === "tag") {
     console.log((await tagCurrentPr()).message);
     return;
   }
+  if (selected.name === "version") {
+    console.log(versionText());
+    return;
+  }
+  if (selected.name === "update") {
+    console.log(await updateRespawn());
+    return;
+  }
 
   const result =
     selected.name === "resume-pr"
@@ -85,6 +107,9 @@ function helpText(): string {
     "  respawn <pr-url|number>",
     "  respawn list",
     "  respawn init",
+    "  respawn import",
+    "  respawn version",
+    "  respawn update",
   ].join("\n");
 }
 

package/src/commands/import.ts

@@ -0,0 +1,98 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { listAllTranscripts } from "../agents";
+import type { ImportableTranscript } from "../agents/types";
+import { gitInfoForCwd, type GitInfo } from "../git";
+import {
+  defaultIndexPath,
+  readIndex,
+  recordSession,
+  type SavedSession,
+} from "../index-file";
+import { createGist } from "../storage/gist";
+
+export type ImportResult = {
+  imported: number;
+  duplicates: number;
+  skipped: number;
+  message: string;
+};
+
+export type ImportDeps = {
+  indexPath?: string;
+  listTranscripts?: typeof listAllTranscripts;
+  gitInfoForCwd?: typeof gitInfoForCwd;
+  createGist?: typeof createGist;
+  now?: () => Date;
+};
+
+export async function importSessions(
+  deps: ImportDeps = {},
+): Promise<ImportResult> {
+  const indexPath = deps.indexPath ?? defaultIndexPath();
+  const transcripts = (deps.listTranscripts ?? listAllTranscripts)();
+  const gitInfo = deps.gitInfoForCwd ?? gitInfoForCwd;
+  const upload = deps.createGist ?? createGist;
+  let imported = 0;
+  let duplicates = 0;
+  let skipped = 0;
+
+  for (const transcript of transcripts) {
+    const info = await gitInfo(transcript.cwd);
+    if (!info) {
+      skipped += 1;
+      continue;
+    }
+
+    const transcriptHash = await hashFile(transcript.path);
+    if (await isDuplicate(indexPath, info, transcript, transcriptHash)) {
+      duplicates += 1;
+      continue;
+    }
+
+    const gistUrl = await upload(
+      transcript.path,
+      `respawn: ${info.repo}@${info.branch}`,
+    );
+    const session: SavedSession = {
+      repo: info.repo,
+      branch: info.branch,
+      gistUrl,
+      sessionId: transcript.sessionId,
+      sha: info.sha,
+      agent: transcript.agent,
+      savedAt: transcript.savedAt ?? (deps.now ?? (() => new Date()))().toISOString(),
+      relativePath: transcript.relativePath,
+      transcriptHash,
+    };
+    await recordSession(indexPath, session);
+    imported += 1;
+  }
+
+  return {
+    imported,
+    duplicates,
+    skipped,
+    message: `Imported ${imported} sessions, skipped ${duplicates} duplicates and ${skipped} unavailable worktrees`,
+  };
+}
+
+async function isDuplicate(
+  indexPath: string,
+  info: GitInfo,
+  transcript: ImportableTranscript,
+  transcriptHash: string,
+): Promise<boolean> {
+  const index = await readIndex(indexPath);
+  return index.sessions.some(
+    (session) =>
+      session.repo === info.repo &&
+      session.branch === info.branch &&
+      session.agent === transcript.agent &&
+      session.transcriptHash === transcriptHash,
+  );
+}
+
+async function hashFile(path: string): Promise<string> {
+  return createHash("sha256").update(await readFile(path)).digest("hex");
+}

package/src/commands/update.ts

@@ -0,0 +1,26 @@
+import packageJson from "../../package.json" with { type: "json" };
+import { runCommand, type RunCommand } from "../shell";
+
+export const currentVersion = packageJson.version;
+
+export function versionText(version = currentVersion): string {
+  return `respawn-session ${version}`;
+}
+
+export type UpdateDeps = {
+  currentVersion?: string;
+  run?: RunCommand;
+};
+
+export async function updateRespawn(deps: UpdateDeps = {}): Promise<string> {
+  const version = deps.currentVersion ?? currentVersion;
+  const run = deps.run ?? runCommand;
+  const latest = (await run("npm", ["view", "respawn-session", "version"])).trim();
+
+  if (latest === version) {
+    return `respawn-session is already up to date at ${version}`;
+  }
+
+  await run("npm", ["install", "-g", "respawn-session@latest"]);
+  return `Updated respawn-session ${version} -> ${latest}`;
+}

package/src/git.ts

@@ -4,6 +4,12 @@ export async function currentRepo(run: RunCommand = runCommand): Promise<string>
   return (await run("git", ["remote", "get-url", "origin"])).trim();
 }
 
+export type GitInfo = {
+  repo: string;
+  branch: string;
+  sha: string;
+};
+
 export async function currentBranch(
   run: RunCommand = runCommand,
 ): Promise<string> {
@@ -20,3 +26,18 @@ export async function checkoutBranch(
 ): Promise<void> {
   await run("git", ["checkout", branch]);
 }
+
+export async function gitInfoForCwd(
+  cwd: string,
+  run: RunCommand = runCommand,
+): Promise<GitInfo | null> {
+  try {
+    const repo = (await run("git", ["-C", cwd, "remote", "get-url", "origin"])).trim();
+    const branch = (await run("git", ["-C", cwd, "branch", "--show-current"])).trim();
+    const sha = (await run("git", ["-C", cwd, "rev-parse", "HEAD"])).trim();
+    if (!repo || !branch || !sha) return null;
+    return { repo, branch, sha };
+  } catch {
+    return null;
+  }
+}