session-preserver 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# session-preserver
+
+Centralized session history for AI coding CLIs — **Claude Code, Codex, OpenCode** — in one terminal view, sorted recent-first. Read-only: it indexes each tool's own history files, no tracking or wrapping.
+
+Requires Node.js ≥ 18 (22+ for the built-in SQLite reader). No dependencies.
+
+## Run
+
+```bash
+npx session-preserver                    # last 20 sessions across all tools
+npx session-preserver -n 30              # more rows
+npx session-preserver --since 2d         # only last 2 days
+npx session-preserver --tool codex       # one tool only
+npx session-preserver DSA                # search title/project
+npx session-preserver summary <id>       # last exchanges — paste into another CLI to continue
+npx session-preserver show <id>          # full user/assistant conversation
+npx session-preserver path <id>          # raw transcript/db path
+```
+
+`<id>` accepts a unique prefix, e.g. `cx:019efd32`. IDs are prefixed by tool: `cc:` Claude Code, `cx:` Codex, `oc:` OpenCode.
+
+Or install globally and use the short alias:
+
+```bash
+npm i -g session-preserver
+sp --since 1d
+```
+
+## What it reads
+
+| Tool        | Source |
+|-------------|--------|
+| Claude Code | `~/.claude/projects/**/*.jsonl` |
+| Codex       | `~/.codex/session_index.jsonl` + `~/.codex/sessions/` |
+| OpenCode    | `~/.local/share/opencode/opencode.db` |
+
+Nothing is written, modified, or sent anywhere.

package/index.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env -S node --no-warnings
+"use strict";
+process.removeAllListeners("warning"); // node:sqlite experimental warning
+process.on("warning", (w) => { if (w.name !== "ExperimentalWarning") console.warn(w); });
+/* session-preserver - centralized session history for AI CLIs (Claude Code, Codex, OpenCode).
+   Read-only indexer over each tool's own history files. No tracking, no wrapping.
+   Usage:
+     npx session-preserver                  recent sessions across all tools
+     npx session-preserver -n 30 --since 2d --tool codex [query]
+     npx session-preserver show <id>        full user/assistant conversation
+     npx session-preserver summary <id>     last few exchanges (paste into another CLI)
+     npx session-preserver path <id>        raw transcript/db path
+*/
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { DatabaseSync } = require("node:sqlite");
+
+const HOME = os.homedir();
+
+// ---------- helpers ----------
+
+function reltime(d) {
+  const s = (Date.now() - d.getTime()) / 1000;
+  if (s < 0) return "in the future";
+  if (s < 90) return `${Math.floor(s)}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  if (s < 86400 * 30) return `${Math.floor(s / 86400)}d ago`;
+  return d.toISOString().slice(0, 10);
+}
+
+const shortHome = (p) => (p || "").replace(new RegExp("^" + HOME.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")), "~");
+
+function* walk(dir, re) {
+  let ents;
+  try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of ents) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) yield* walk(p, re);
+    else if (re.test(e.name)) yield p;
+  }
+}
+
+function* lines(file) {
+  // ponytail: whole-file read; transcripts are a few MB max. Stream if one ever feels slow.
+  let data;
+  try { data = fs.readFileSync(file, "utf8"); } catch { return; }
+  for (const line of data.split("\n")) if (line.trim()) yield line;
+}
+
+function parseSince(s) {
+  const m = /^(\d+)([smhdw])$/.exec(s.trim());
+  if (!m) { console.error(`--since: bad value '${s}' (use e.g. 30m, 12h, 2d, 1w)`); process.exit(1); }
+  const mult = { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 }[m[2]];
+  return new Date(Date.now() - Number(m[1]) * mult);
+}
+
+const textOf = (c) =>
+  typeof c === "string"
+    ? c
+    : (Array.isArray(c) ? c : [])
+        .filter((x) => x && typeof x === "object" && (x.type === "text" ? true : "text" in x))
+        .map((x) => x.text || "")
+        .join("\n");
+
+const SKIP = (t) => !t.trim() || t.startsWith("<") || t.startsWith("#");
+const oneline = (t, n) => t.replace(/\s+/g, " ").trim().slice(0, n);
+
+// ---------- sources ----------
+
+function claudeSessions() {
+  const base = path.join(HOME, ".claude/projects");
+  const out = [];
+  for (const f of walk(base, /\.jsonl$/)) {
+    try {
+      const proj = "/" + path.basename(path.dirname(f)).replace(/^-/, "").replace(/-/g, "/");
+      let firstUser = "", lastA = "";
+      for (const line of lines(f)) {
+        let rec; try { rec = JSON.parse(line); } catch { continue; }
+        if (rec.type === "user" && !firstUser) {
+          const t = textOf(rec.message && rec.message.content);
+          if (!SKIP(t)) firstUser = oneline(t, 60);
+        } else if (rec.type === "assistant") {
+          const t = textOf(rec.message && rec.message.content);
+          if (!SKIP(t)) lastA = oneline(t, 60);
+        }
+      }
+      out.push({
+        id: "cc:" + path.basename(f, ".jsonl"), tool: "claude", source: f,
+        project: shortHome(proj), title: firstUser || lastA,
+        updated: new Date(fs.statSync(f).mtime),
+      });
+    } catch { /* skip unreadable file */ }
+  }
+  return out;
+}
+
+function codexSessions() {
+  const names = {};
+  const idx = path.join(HOME, ".codex/session_index.jsonl");
+  for (const line of lines(idx)) {
+    try {
+      const r = JSON.parse(line);
+      if (r.id) names[r.id] = { title: r.thread_name || "", updated: r.updated_at || "" };
+    } catch { /* skip */ }
+  }
+  const out = [];
+  for (const f of walk(path.join(HOME, ".codex/sessions"), /^rollout-.*\.jsonl$/)) {
+    try {
+      let meta = null, firstUser = "";
+      for (const line of lines(f)) {
+        let rec; try { rec = JSON.parse(line); } catch { continue; }
+        if (rec.type === "session_meta") meta = rec.payload;
+        else if (rec.type === "response_item" && !firstUser) {
+          const pl = rec.payload || {};
+          if (pl.type === "message" && pl.role === "user") {
+            const t = textOf(pl.content);
+            if (!SKIP(t)) firstUser = oneline(t, 60);
+          }
+        }
+      }
+      const sid = meta ? meta.id || meta.session_id : path.basename(f, ".jsonl");
+      const idxRec = names[sid] || {};
+      let updated;
+      try { updated = new Date(idxRec.updated || (meta && meta.timestamp)); }
+      catch { updated = new Date(fs.statSync(f).mtime); }
+      if (isNaN(updated)) updated = new Date(fs.statSync(f).mtime);
+      out.push({
+        id: "cx:" + sid, tool: "codex", source: f,
+        project: shortHome(meta ? meta.cwd : ""),
+        title: idxRec.title || firstUser, updated,
+      });
+    } catch { /* skip */ }
+  }
+  return out;
+}
+
+function opencodeSessions() {
+  const dbPath = path.join(HOME, ".local/share/opencode/opencode.db");
+  if (!fs.existsSync(dbPath)) return [];
+  try {
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    const rows = db
+      .prepare("SELECT id, title, directory, time_updated FROM session ORDER BY time_updated DESC LIMIT 500")
+      .all();
+    db.close();
+    return rows.map((r) => ({
+      id: "oc:" + r.id, tool: "opencode", source: dbPath,
+      project: shortHome(r.directory || ""), title: oneline(r.title || "", 60),
+      updated: new Date(Number(r.time_updated)),
+    }));
+  } catch { return []; }
+}
+
+const SOURCES = { claude: claudeSessions, codex: codexSessions, opencode: opencodeSessions };
+
+function allSessions() {
+  return Object.values(SOURCES)
+    .flatMap((fn) => { try { return fn(); } catch { return []; } })
+    .sort((a, b) => b.updated - a.updated);
+}
+
+function find(prefix) {
+  const hits = allSessions().filter((s) => s.id.startsWith(prefix));
+  if (!hits.length) { console.error(`no session matches '${prefix}'`); process.exit(1); }
+  if (hits.length > 1) {
+    console.error("ambiguous id, matches:\n" + hits.map((h) => `  ${h.id}  ${h.title.slice(0, 50)}`).join("\n"));
+    process.exit(1);
+  }
+  return hits[0];
+}
+
+// ---------- conversation readers ----------
+
+function* conversation(sess) {
+  if (sess.tool === "claude") {
+    for (const line of lines(sess.source)) {
+      let rec; try { rec = JSON.parse(line); } catch { continue; }
+      if (rec.type === "user" || rec.type === "assistant") {
+        const t = textOf(rec.message && rec.message.content).trim();
+        if (t && !t.startsWith("<")) yield [rec.type, t];
+      }
+    }
+  } else if (sess.tool === "codex") {
+    for (const line of lines(sess.source)) {
+      let rec; try { rec = JSON.parse(line); } catch { continue; }
+      if (rec.type === "response_item") {
+        const pl = rec.payload || {};
+        if (pl.type === "message") {
+          const t = textOf(pl.content).trim();
+          if (t && !t.startsWith("<")) yield [pl.role || "?", t];
+        }
+      }
+    }
+  } else if (sess.tool === "opencode") {
+    const db = new DatabaseSync(sess.source, { readOnly: true });
+    const sid = sess.id.slice(3);
+    try {
+      const msgs = db.prepare("SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created").all(sid);
+      const partStmt = db.prepare("SELECT data FROM part WHERE message_id = ? ORDER BY time_created");
+      for (const m of msgs) {
+        let role = "?";
+        try { role = JSON.parse(m.data).role || "?"; } catch { /* keep ? */ }
+        for (const p of partStmt.all(m.id)) {
+          try {
+            const d = JSON.parse(p.data);
+            if (d.type === "text" && d.text && d.text.trim()) yield [role, d.text];
+          } catch { /* skip */ }
+        }
+      }
+    } finally { db.close(); }
+  }
+}
+
+function render(sess, pairs) {
+  const head = `# ${sess.tool} session ${sess.id}\nproject: ${sess.project}   updated: ${sess.updated.toISOString().slice(0, 16).replace("T", " ")} UTC\n`;
+  return head + pairs.map(([r, t]) => `\n## ${r}\n\n${t}\n`).join("");
+}
+
+// ---------- commands ----------
+
+function cmdLs(args) {
+  let rows = allSessions();
+  if (args.tool) rows = rows.filter((r) => r.tool === args.tool);
+  if (args.since) { const cut = parseSince(args.since); rows = rows.filter((r) => r.updated >= cut); }
+  if (args.query) { const q = args.query.toLowerCase(); rows = rows.filter((r) => (r.title + " " + r.project).toLowerCase().includes(q)); }
+  rows = rows.slice(0, args.n);
+  if (!rows.length) { console.log("no sessions found"); return; }
+  const idW = Math.max(...rows.map((r) => r.id.length)) ;
+  console.log(`${"ID".padEnd(idW + 1)} ${"TOOL".padEnd(9)} ${"WHEN".padEnd(10)} ${"PROJECT".padEnd(38)} TITLE`);
+  for (const r of rows)
+    console.log(`${r.id.padEnd(idW + 1)} ${r.tool.padEnd(9)} ${reltime(r.updated).padEnd(10)} ${r.project.slice(-37).padEnd(38)} ${r.title.slice(0, 60)}`);
+}
+
+function cmdShow(id, n) {
+  const sess = find(id);
+  let pairs = [...conversation(sess)];
+  if (n != null) pairs = pairs.slice(-n);
+  process.stdout.write(render(sess, pairs));
+}
+
+function cmdSummary(id) {
+  const sess = find(id);
+  const pairs = [...conversation(sess)].filter(([r]) => r === "user" || r === "assistant").slice(-6);
+  process.stdout.write(render(sess, pairs));
+}
+
+// ---------- main ----------
+
+function usage(code) {
+  console.log(`session-preserver - centralized AI CLI session history
+
+Usage:
+  session-preserver [ls] [-n N] [--since 2d] [--tool claude|codex|opencode] [query]
+  session-preserver show <id> [-n N]
+  session-preserver summary <id>
+  session-preserver path <id>
+
+ids accept unique prefixes, e.g.  cx:019efd32`);
+  process.exit(code);
+}
+
+const argv = process.argv.slice(2);
+if (argv.includes("-h") || argv.includes("--help")) usage(0);
+
+const COMMANDS = new Set(["ls", "show", "summary", "path"]);
+let cmd = "ls";
+if (COMMANDS.has(argv[0])) cmd = argv.shift();
+
+if (cmd === "ls") {
+  const args = { n: 20, since: null, tool: null, query: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "-n") args.n = Number(argv[++i]);
+    else if (argv[i] === "--since") args.since = argv[++i];
+    else if (argv[i] === "--tool") {
+      args.tool = argv[++i];
+      if (!SOURCES[args.tool]) { console.error(`unknown tool '${args.tool}' (claude|codex|opencode)`); process.exit(1); }
+    } else if (!args.query) args.query = argv[i];
+    else usage(1);
+  }
+  cmdLs(args);
+} else {
+  const id = argv[0];
+  if (!id) usage(1);
+  if (cmd === "show") {
+    const i = argv.indexOf("-n");
+    cmdShow(id, i > -1 ? Number(argv[i + 1]) : null);
+  } else if (cmd === "summary") cmdSummary(id);
+  else if (cmd === "path") console.log(find(id).source);
+}

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "session-preserver",
+  "version": "0.1.0",
+  "description": "Centralized session history for AI CLIs — Claude Code, Codex, OpenCode. Read-only.",
+  "license": "MIT",
+  "bin": { "session-preserver": "index.js", "sp": "index.js" },
+  "engines": { "node": ">=18" },
+  "files": ["index.js", "README.md"],
+  "keywords": ["claude", "codex", "opencode", "ai", "cli", "history", "session"]
+}