respawn-session 0.0.2 → 0.0.4

package/README.md

@@ -17,56 +17,116 @@ 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
 ```
 
+## 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 <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 |
+
 ## 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.4",
   "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";
 
 export function encodeClaudeProjectPath(cwd: string): string {
-  return cwd.replaceAll("/", "-");
+  return cwd.replace(/[^A-Za-z0-9._-]/g, "-");
 }
 
 export function transcriptPath(
@@ -27,14 +27,55 @@ 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];
 }
+
+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/cli.ts

@@ -4,6 +4,7 @@ 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" }
@@ -12,6 +13,8 @@ export type Route =
   | { name: "list" }
   | { name: "init" }
   | { name: "tag" }
+  | { name: "version" }
+  | { name: "update" }
   | { name: "resume"; branch: string }
   | { name: "resume-pr"; prRef: string };
 
@@ -20,12 +23,16 @@ 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 === "tag" ||
+    command === "update"
   ) {
     return { name: command };
   }
@@ -61,6 +68,14 @@ export async function main(args = Bun.argv.slice(2)): Promise<void> {
     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 +100,8 @@ function helpText(): string {
     "  respawn <pr-url|number>",
     "  respawn list",
     "  respawn init",
+    "  respawn version",
+    "  respawn update",
   ].join("\n");
 }
 

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}`;
+}