respawn-session 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Angela Felicia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# respawn-session
+
+Save your Claude Code or Codex session to a git branch and resume it later from another worktree or machine.
+
+The session is the transcript. `respawn` uploads that transcript to a private GitHub gist, records it in `~/.respawn/index.json`, restores it later, checks out the branch, and starts the same agent with its resume command.
+
+## Install
+
+```sh
+npm install -g respawn-session
+```
+
+The package ships a Bun TypeScript CLI with no build step. Bun 1.0 or newer and the GitHub CLI are required:
+
+```sh
+bun --version
+gh auth status
+```
+
+## Usage
+
+Initialize local storage and install a Claude Code Stop hook:
+
+```sh
+respawn init
+```
+
+Save the current active agent session from inside a git worktree:
+
+```sh
+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:
+
+```sh
+bun --version
+gh auth status
+```
+
+Run npm's packaging checks first:
+
+```sh
+npm pack --dry-run
+npm publish --dry-run
+```
+
+Publish the package:
+
+```sh
+npm publish
+```
+
+If npm returns a 403 saying two-factor authentication is required, publish with a current OTP code:
+
+```sh
+npm publish --otp <your-current-2fa-code>
+```
+
+After publish, users can install the CLI globally:
+
+```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:
+
+1. Claude Code via `CLAUDE_SESSION_ID`
+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:
+
+```sh
+gh gist create <transcript>.jsonl --desc "respawn: <repo>@<branch>"
+```
+
+GitHub CLI gists are secret by default unless `--public` is passed. `respawn` does not pass `--public`.
+
+The local index lives at:
+
+```sh
+~/.respawn/index.json
+```
+
+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.
+
+## Agent Paths
+
+Claude Code transcripts are restored to:
+
+```sh
+~/.claude/projects/<encoded-cwd>/<session-id>.jsonl
+```
+
+Codex transcripts are restored under their saved relative path in:
+
+```sh
+~/.codex/sessions/
+```
+
+Resume commands:
+
+```sh
+claude --resume <session-id>
+codex resume <session-id>
+```
+
+## v0 Limits
+
+There is no hosted service, no telemetry, and no secret redaction. Transcripts can contain proprietary code or credentials, so use storage you control and treat gists as sensitive even when secret.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "respawn-session",
+  "version": "0.0.1",
+  "description": "Save and resume Claude Code or Codex agent sessions by git branch.",
+  "type": "module",
+  "bin": {
+    "respawn": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/angelafeliciaa/respawn-session.git"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "latest"
+  }
+}

package/src/agents/claude.ts

@@ -0,0 +1,40 @@
+import { existsSync } 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("/", "-");
+}
+
+export function transcriptPath(
+  sessionId: string,
+  options: LocateOptions = {},
+): string {
+  const cwd = options.cwd ?? process.cwd();
+  const home = options.home ?? homedir();
+  return join(
+    home,
+    ".claude",
+    "projects",
+    encodeClaudeProjectPath(cwd),
+    `${sessionId}.jsonl`,
+  );
+}
+
+export function locateTranscript(
+  options: LocateOptions = {},
+): LocatedTranscript | null {
+  const env = options.env ?? process.env;
+  const sessionId = env.CLAUDE_SESSION_ID;
+  if (!sessionId) return null;
+
+  const path = transcriptPath(sessionId, options);
+  if (!existsSync(path)) return null;
+
+  return { agent: "claude", path, sessionId };
+}
+
+export function resumeCmd(sessionId: string): string[] {
+  return ["claude", "--resume", sessionId];
+}

package/src/agents/codex.ts

@@ -0,0 +1,103 @@
+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";
+
+const uuidPattern =
+  /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+
+type CodexMeta = {
+  id: string;
+  cwd?: string;
+};
+
+export function codexSessionsDir(home = homedir()): string {
+  return join(home, ".codex", "sessions");
+}
+
+export function sessionIdFromCodexPath(path: string): string | null {
+  return basename(path).match(uuidPattern)?.[0] ?? null;
+}
+
+export function transcriptPath(relativePath: string, home = homedir()): string {
+  return join(codexSessionsDir(home), relativePath);
+}
+
+export function locateTranscript(
+  options: LocateOptions = {},
+): LocatedTranscript | null {
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const home = options.home ?? homedir();
+  const sessionsDir = codexSessionsDir(home);
+
+  const envPath = env.CODEX_TUI_SESSION_LOG_PATH;
+  if (envPath && existsSync(envPath)) {
+    const located = locatedFromPath(envPath, cwd, sessionsDir, true);
+    if (located) return located;
+  }
+
+  if (!existsSync(sessionsDir)) return null;
+
+  const desiredId = env.CODEX_SESSION_ID;
+  const candidates = walkJsonl(sessionsDir)
+    .map((path) => locatedFromPath(path, cwd, sessionsDir, false))
+    .filter((session): session is LocatedTranscript => Boolean(session))
+    .filter((session) => !desiredId || session.sessionId === desiredId);
+
+  return [...candidates]
+    .sort((a, b) => statSync(a.path).mtimeMs - statSync(b.path).mtimeMs)
+    .at(-1) ?? null;
+}
+
+export function resumeCmd(sessionId: string): string[] {
+  return ["codex", "resume", sessionId];
+}
+
+function locatedFromPath(
+  path: string,
+  cwd: string,
+  sessionsDir: string,
+  requireMatchingCwd: boolean,
+): LocatedTranscript | null {
+  const meta = readCodexMeta(path);
+  const sessionId = meta?.id ?? sessionIdFromCodexPath(path);
+  if (!sessionId) return null;
+  if (requireMatchingCwd && meta?.cwd && meta.cwd !== cwd) return null;
+  if (!requireMatchingCwd && meta?.cwd !== cwd) return null;
+
+  const rel = relative(sessionsDir, path);
+  return {
+    agent: "codex",
+    path,
+    sessionId,
+    relativePath: rel.startsWith("..") ? undefined : rel,
+  };
+}
+
+function readCodexMeta(path: string): CodexMeta | null {
+  try {
+    const lines = readFileSync(path, "utf8").split("\n").slice(0, 20);
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      const parsed = JSON.parse(line) as {
+        type?: string;
+        payload?: { id?: string; cwd?: string };
+      };
+      if (parsed.type === "session_meta" && parsed.payload?.id) {
+        return { id: parsed.payload.id, cwd: parsed.payload.cwd };
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function walkJsonl(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return walkJsonl(path);
+    return entry.isFile() && entry.name.endsWith(".jsonl") ? [path] : [];
+  });
+}

package/src/agents/index.ts

@@ -0,0 +1,30 @@
+import type { LocatedTranscript, LocateOptions } from "./types";
+import * as claude from "./claude";
+import * as codex from "./codex";
+
+export function locateActiveTranscript(
+  options: LocateOptions = {},
+): LocatedTranscript | null {
+  return (
+    claude.locateTranscript(options) ??
+    codex.locateTranscript(options)
+  );
+}
+
+export function resumeCmd(agent: LocatedTranscript["agent"], sessionId: string): string[] {
+  if (agent === "claude") return claude.resumeCmd(sessionId);
+  return codex.resumeCmd(sessionId);
+}
+
+export function targetTranscriptPath(
+  transcript: Pick<LocatedTranscript, "agent" | "sessionId" | "relativePath">,
+  options: LocateOptions = {},
+): string {
+  if (transcript.agent === "claude") {
+    return claude.transcriptPath(transcript.sessionId, options);
+  }
+  if (!transcript.relativePath) {
+    throw new Error("Codex session is missing its transcript relative path");
+  }
+  return codex.transcriptPath(transcript.relativePath, options.home);
+}

package/src/agents/types.ts

@@ -0,0 +1,14 @@
+import type { AgentName } from "../index-file";
+
+export type LocatedTranscript = {
+  agent: AgentName;
+  path: string;
+  sessionId: string;
+  relativePath?: string;
+};
+
+export type LocateOptions = {
+  cwd?: string;
+  home?: string;
+  env?: NodeJS.ProcessEnv;
+};

package/src/cli.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env bun
+import { initRespawn } from "./commands/init";
+import { listSessions } from "./commands/list";
+import { resumeSession } from "./commands/resume";
+import { saveSession } from "./commands/save";
+
+export type Route =
+  | { name: "help" }
+  | { name: "save" }
+  | { name: "list" }
+  | { name: "init" }
+  | { name: "resume"; branch: 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") {
+    return { name: command };
+  }
+  return { name: "resume", branch: command };
+}
+
+export async function main(args = Bun.argv.slice(2)): Promise<void> {
+  const selected = route(args);
+  if (selected.name === "help") {
+    console.log(helpText());
+    return;
+  }
+  if (selected.name === "save") {
+    console.log((await saveSession()).message);
+    return;
+  }
+  if (selected.name === "list") {
+    console.log((await listSessions()) || "No saved sessions");
+    return;
+  }
+  if (selected.name === "init") {
+    console.log(await initRespawn());
+    return;
+  }
+
+  const result = await resumeSession(selected.branch);
+  const [cmd, ...cmdArgs] = result.command;
+  const proc = Bun.spawn([cmd, ...cmdArgs], {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  process.exit(await proc.exited);
+}
+
+function helpText(): string {
+  return [
+    "Usage:",
+    "  respawn save",
+    "  respawn <branch>",
+    "  respawn list",
+    "  respawn init",
+  ].join("\n");
+}
+
+if (import.meta.main) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/src/commands/init.ts

@@ -0,0 +1,53 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { defaultIndexPath, readIndex, writeIndex } from "../index-file";
+
+type ClaudeSettings = {
+  hooks?: Record<string, Array<{ matcher?: string; hooks?: HookCommand[] }>>;
+};
+
+type HookCommand = {
+  type: "command";
+  command: string;
+};
+
+export type InitDeps = {
+  home?: string;
+  indexPath?: string;
+};
+
+export async function initRespawn(deps: InitDeps = {}): Promise<string> {
+  const home = deps.home ?? homedir();
+  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 stopHooks = settings.hooks?.Stop ?? [];
+  const command = "respawn save || true";
+  const alreadyInstalled = stopHooks.some((group) =>
+    group.hooks?.some((hook) => hook.command === command),
+  );
+
+  if (!alreadyInstalled) {
+    stopHooks.push({
+      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;
+  }
+}

package/src/commands/list.ts

@@ -0,0 +1,21 @@
+import { defaultIndexPath, readIndex } from "../index-file";
+
+export type ListDeps = {
+  indexPath?: string;
+};
+
+export async function listSessions(deps: ListDeps = {}): Promise<string> {
+  const index = await readIndex(deps.indexPath ?? defaultIndexPath());
+  return index.sessions
+    .map((session) =>
+      [
+        session.savedAt,
+        session.agent,
+        `${session.repo}@${session.branch}`,
+        session.sessionId,
+        session.sha,
+        session.gistUrl,
+      ].join(" "),
+    )
+    .join("\n");
+}

package/src/commands/resume.ts

@@ -0,0 +1,48 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resumeCmd, targetTranscriptPath } from "../agents";
+import { checkoutBranch, currentRepo } from "../git";
+import {
+  defaultIndexPath,
+  findLatestSession,
+  type SavedSession,
+} from "../index-file";
+import { downloadGist } from "../storage/gist";
+
+export type ResumeDeps = {
+  indexPath?: string;
+  currentRepo?: typeof currentRepo;
+  downloadGist?: typeof downloadGist;
+  checkoutBranch?: typeof checkoutBranch;
+  targetTranscriptPath?: typeof targetTranscriptPath;
+};
+
+export async function resumeSession(
+  branch: string,
+  deps: ResumeDeps = {},
+): Promise<{
+  command: string[];
+  path: string;
+  session: SavedSession;
+}> {
+  const repo = await (deps.currentRepo ?? currentRepo)();
+  const session = await findLatestSession(deps.indexPath ?? defaultIndexPath(), {
+    repo,
+    branch,
+  });
+  if (!session) {
+    throw new Error(`No saved respawn session found for ${repo}@${branch}`);
+  }
+
+  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.checkoutBranch ?? checkoutBranch)(branch);
+
+  return {
+    command: resumeCmd(session.agent, session.sessionId),
+    path,
+    session,
+  };
+}

package/src/commands/save.ts

@@ -0,0 +1,56 @@
+import { locateActiveTranscript } from "../agents";
+import { currentBranch, currentRepo, currentSha } from "../git";
+import {
+  defaultIndexPath,
+  recordSession,
+  type SavedSession,
+} from "../index-file";
+import { createGist } from "../storage/gist";
+
+export type SaveDeps = {
+  indexPath?: string;
+  locateActiveTranscript?: typeof locateActiveTranscript;
+  currentRepo?: typeof currentRepo;
+  currentBranch?: typeof currentBranch;
+  currentSha?: typeof currentSha;
+  createGist?: typeof createGist;
+  now?: () => Date;
+};
+
+export async function saveSession(deps: SaveDeps = {}): Promise<{
+  message: string;
+  session: SavedSession;
+}> {
+  const locate = deps.locateActiveTranscript ?? locateActiveTranscript;
+  const transcript = locate();
+  if (!transcript) {
+    throw new Error(
+      "No active Claude Code or Codex session transcript found. Run respawn save inside an active agent session.",
+    );
+  }
+
+  const repo = await (deps.currentRepo ?? currentRepo)();
+  const branch = await (deps.currentBranch ?? currentBranch)();
+  const sha = await (deps.currentSha ?? currentSha)();
+  const gistUrl = await (deps.createGist ?? createGist)(
+    transcript.path,
+    `respawn: ${repo}@${branch}`,
+  );
+
+  const session: SavedSession = {
+    repo,
+    branch,
+    gistUrl,
+    sessionId: transcript.sessionId,
+    sha,
+    agent: transcript.agent,
+    savedAt: (deps.now ?? (() => new Date()))().toISOString(),
+    relativePath: transcript.relativePath,
+  };
+
+  await recordSession(deps.indexPath ?? defaultIndexPath(), session);
+  return {
+    message: `Saved ${session.agent} session ${session.sessionId} for ${branch}`,
+    session,
+  };
+}

package/src/git.ts

@@ -0,0 +1,22 @@
+import { runCommand, type RunCommand } from "./shell";
+
+export async function currentRepo(run: RunCommand = runCommand): Promise<string> {
+  return (await run("git", ["remote", "get-url", "origin"])).trim();
+}
+
+export async function currentBranch(
+  run: RunCommand = runCommand,
+): Promise<string> {
+  return (await run("git", ["branch", "--show-current"])).trim();
+}
+
+export async function currentSha(run: RunCommand = runCommand): Promise<string> {
+  return (await run("git", ["rev-parse", "HEAD"])).trim();
+}
+
+export async function checkoutBranch(
+  branch: string,
+  run: RunCommand = runCommand,
+): Promise<void> {
+  await run("git", ["checkout", branch]);
+}

package/src/index-file.ts

@@ -0,0 +1,82 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type AgentName = "claude" | "codex";
+
+export type SavedSession = {
+  repo: string;
+  branch: string;
+  gistUrl: string;
+  sessionId: string;
+  sha: string;
+  agent: AgentName;
+  savedAt: string;
+  relativePath?: string;
+};
+
+export type RespawnIndex = {
+  version: 1;
+  sessions: SavedSession[];
+};
+
+export type SessionQuery = {
+  repo: string;
+  branch: string;
+};
+
+export function defaultIndexPath(home = homedir()): string {
+  return join(home, ".respawn", "index.json");
+}
+
+export async function readIndex(path = defaultIndexPath()): Promise<RespawnIndex> {
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw) as RespawnIndex;
+    return {
+      version: 1,
+      sessions: Array.isArray(parsed.sessions) ? parsed.sessions : [],
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { version: 1, sessions: [] };
+    }
+    throw error;
+  }
+}
+
+export async function writeIndex(
+  path: string,
+  index: RespawnIndex,
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(index, null, 2)}\n`);
+}
+
+export async function recordSession(
+  path: string,
+  session: SavedSession,
+): Promise<SavedSession> {
+  const index = await readIndex(path);
+  index.sessions.push(session);
+  await writeIndex(path, index);
+  return session;
+}
+
+export async function findSessions(
+  path: string,
+  query: SessionQuery,
+): Promise<SavedSession[]> {
+  const index = await readIndex(path);
+  return index.sessions.filter(
+    (session) => session.repo === query.repo && session.branch === query.branch,
+  );
+}
+
+export async function findLatestSession(
+  path: string,
+  query: SessionQuery,
+): Promise<SavedSession | null> {
+  const sessions = await findSessions(path, query);
+  return [...sessions].sort((a, b) => a.savedAt.localeCompare(b.savedAt)).at(-1) ?? null;
+}

package/src/shell.ts

@@ -0,0 +1,21 @@
+export type RunCommand = (cmd: string, args: string[]) => Promise<string>;
+
+export const runCommand: RunCommand = async (cmd, args) => {
+  const proc = Bun.spawn([cmd, ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  if (exitCode !== 0) {
+    throw new Error(
+      `${cmd} ${args.join(" ")} failed with exit ${exitCode}: ${stderr.trim()}`,
+    );
+  }
+
+  return stdout;
+};

package/src/storage/gist.ts

@@ -0,0 +1,24 @@
+import { runCommand, type RunCommand } from "../shell";
+
+export function gistIdFromUrl(value: string): string {
+  const trimmed = value.trim();
+  const segments = trimmed.split("/").filter(Boolean);
+  return segments.at(-1) ?? trimmed;
+}
+
+export async function createGist(
+  transcriptPath: string,
+  description: string,
+  run: RunCommand = runCommand,
+): Promise<string> {
+  return (
+    await run("gh", ["gist", "create", transcriptPath, "--desc", description])
+  ).trim();
+}
+
+export async function downloadGist(
+  gistUrl: string,
+  run: RunCommand = runCommand,
+): Promise<string> {
+  return run("gh", ["gist", "view", gistIdFromUrl(gistUrl), "--raw"]);
+}