ccnav 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Brown
+
+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,78 @@
+# ccnav — Claude Codex Navigator
+
+A terminal picker for the Claude Code and Codex sessions on this machine. Pick one and it resumes in the directory it was started in, whichever agent it belongs to.
+
+Works on Windows, macOS and Linux with Node 20 or later. Everything that differs by OS (launching the agent, new tabs, Finder/Explorer, clipboard, shell function) is in `src/platform.mjs`; everything that differs by agent is in `src/providers/`.
+
+## Install
+
+From a checkout (any OS):
+
+```sh
+npm install
+npm link                # puts `ccnav` on PATH
+ccnav --install-shell   # optional: leave your shell in the session's directory afterwards
+```
+
+Or build a tarball once and install it anywhere, e.g. on a Mac:
+
+```sh
+npm pack                        # -> ccnav-1.0.0.tgz
+npm install -g ./ccnav-1.0.0.tgz
+```
+
+`--install-shell` writes a function to the right file for your shell: the PowerShell `$PROFILE` on Windows, `~/.zshrc` for zsh (macOS default), `~/.bash_profile` (macOS) or `~/.bashrc` (Linux) for bash, and `~/.config/fish/functions/ccnav.fish` for fish. Running it again replaces the block rather than adding a second one.
+
+New tabs (`t`) use Windows Terminal, iTerm2, WezTerm, kitty, GNOME Terminal or Konsole. Terminal.app gets a new window, because real tabs need Accessibility permission.
+
+## Use
+
+```
+ccnav                  open the picker
+ccnav --claude         only Claude Code sessions
+ccnav --codex          only Codex sessions
+ccnav --list           print sessions and exit
+ccnav --json           print sessions as JSON and exit
+ccnav --model opus     any other arguments are passed to the agent
+```
+
+| Key | Action |
+|---|---|
+| ↑ ↓ / j k, PgUp PgDn, g G | move |
+| [ ] | jump to the previous / next directory |
+| Tab | cycle agents: both → Claude → Codex |
+| Enter | resume in its directory |
+| t | resume in a new terminal tab (picker stays open) |
+| f | fork (resume under a new session id) |
+| n | new session in that directory, with the same agent |
+| o | open the directory in Explorer, Finder or the Linux file manager |
+| c | copy the session id |
+| / | filter titles, paths, branches and prompts; Tab switches to full-transcript search |
+| s | cycle sort: last used, created, size, directory name (sessions stay grouped by directory) |
+| x | archive the selected session |
+| X | archive every listed session not used in N days |
+| a | show or hide Claude Desktop scratch sessions |
+| q / Esc | quit |
+
+`◆` in cyan marks a Claude Code session, `●` in green a Codex one.
+
+## Where sessions come from
+
+| | Claude Code | Codex |
+|---|---|---|
+| Files | `~/.claude/projects/<encoded-dir>/<id>.jsonl` | `~/.codex/sessions/YYYY/MM/DD/rollout-<time>-<id>.jsonl` |
+| Override | `$CLAUDE_CONFIG_DIR` | `$CODEX_HOME` |
+| Title | `ai-title` record | `thread_name` in `~/.codex/session_index.jsonl`, else the first prompt |
+| Resume / fork | `claude --resume <id>` / `--fork-session` | `codex resume <id>` / `codex fork <id>` |
+| Hidden | subagent sidechain folders, Desktop scratch workspaces | subagent threads spawned by other sessions |
+
+Only the first and last 256 KB of each transcript are read when listing, so a 21 MB session costs the same as a small one. Full-text search reads whole files.
+
+Archived sessions move to `~/.claude/ccnav-archive/` or `~/.codex/ccnav-archive/`, keeping the folders they had underneath (`<project>/` for Claude, `YYYY/MM/DD/` for Codex). Moving a file back restores it. Sessions used in the last 10 minutes are never archived, because they may still be open. Archiving a Codex session leaves its line in `session_index.jsonl`; that is harmless but not cleaned up.
+
+## Test
+
+```sh
+npm test                                                               # unit + UI tests, any OS
+docker run --rm -v "$PWD:/src:ro" node:24 bash /src/test/docker-e2e.sh # Linux install + zsh end-to-end
+```

package/bin/ccnav.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import React from 'react';
+import { render } from 'ink';
+import { App } from '../src/app.mjs';
+import { ago, humanSize, listSessions, providerOf, shortPath } from '../src/sessions.mjs';
+import { installShellFunction, launchAgent, reportCwd } from '../src/actions.mjs';
+
+const args = process.argv.slice(2);
+
+if (args.includes('-h') || args.includes('--help')) {
+  console.log(`ccnav - Claude Codex Navigator: pick a Claude Code or Codex session
+and resume it in its own directory
+
+usage:
+  ccnav                  open the session picker
+  ccnav --claude         only Claude Code sessions
+  ccnav --codex          only Codex sessions
+  ccnav --list           print sessions as a table and exit
+  ccnav --json           print sessions as JSON and exit
+  ccnav --install-shell  add a shell function (PowerShell, zsh, bash or fish) so
+                         your shell is left in the session's directory afterwards
+
+Any other arguments are passed to the agent (e.g. ccnav --model opus).`);
+  process.exit(0);
+}
+
+if (args.includes('--install-shell')) {
+  const { shell, file, reload } = installShellFunction();
+  console.log(`ccnav ${shell} function written to ${file}\nto use it now: ${reload}`);
+  process.exit(0);
+}
+
+// PowerShell swallows a bare `--`, so anything ccnav doesn't recognise goes to the agent.
+const OWN_FLAGS = new Set(['--list', '--json', '--install-shell', '--claude', '--codex', '-h', '--help', '--']);
+const passthrough = args.filter(a => !OWN_FLAGS.has(a));
+const agents = ['claude', 'codex'].filter(a => args.includes(`--${a}`));
+const sessions = listSessions(agents.length ? { agents } : {});
+
+if (args.includes('--json')) {
+  console.log(JSON.stringify(sessions, null, 2));
+  process.exit(0);
+}
+
+if (args.includes('--list')) {
+  for (const s of sessions) {
+    console.log([s.agent.padEnd(6), ago(s.lastUsed).padEnd(9), ago(s.created).padEnd(9), humanSize(s.size).padStart(6),
+      shortPath(s.cwd).padEnd(40), (s.title || s.firstPrompt).replace(/\s+/g, ' ').slice(0, 60)].join('  '));
+  }
+  process.exit(0);
+}
+
+if (!process.stdin.isTTY) {
+  console.error('ccnav needs an interactive terminal (use --list or --json otherwise)');
+  process.exit(1);
+}
+
+let choice = null;
+const app = render(React.createElement(App, { sessions, passthrough, onChoose: c => { choice = c; } }));
+await app.waitUntilExit();
+
+if (!choice) process.exit(0);
+const { action, session } = choice;
+
+const provider = providerOf(session);
+const agentArgs = provider.launchArgs(action, session, passthrough);
+
+reportCwd(session.cwd);
+console.log(`\n→ ${session.cwd}\n→ ${provider.command} ${agentArgs.join(' ')}\n`);
+process.exit(await launchAgent(provider.command, session.cwd, agentArgs));

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "ccnav",
+  "version": "1.0.0",
+  "description": "Claude Codex Navigator - pick a Claude Code or Codex session and resume it in its directory",
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "tui",
+    "cli",
+    "codex"
+  ],
+  "author": "rts-mb",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ccnav": "bin/ccnav.mjs"
+  },
+  "dependencies": {
+    "ink": "^7.1.1",
+    "react": "^19.3.0"
+  },
+  "devDependencies": {
+    "ink-testing-library": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rts-mb/ccnav.git"
+  },
+  "homepage": "https://github.com/rts-mb/ccnav#readme",
+  "bugs": {
+    "url": "https://github.com/rts-mb/ccnav/issues"
+  }
+}

package/src/actions.mjs

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export { copyToClipboard, installShellFunction, launchAgent, openFolder, openInNewTab } from './platform.mjs';
+
+// Sessions touched this recently may be open in another terminal.
+export const LIVE_WINDOW_MS = 10 * 60 * 1000;
+export const isMaybeLive = s => Date.now() - s.lastUsed < LIVE_WINDOW_MS;
+
+// Case-insensitive search through the whole transcript; returns a short snippet or null.
+export function searchTranscript(session, query) {
+  const q = query.toLowerCase();
+  let text;
+  try { text = fs.readFileSync(session.file, 'utf8'); } catch { return null; }
+  const lower = text.toLowerCase();
+  const idx = lower.indexOf(q);
+  if (idx < 0) return null;
+  // Prefer the matching string value from the parsed record over raw JSON.
+  const lineStart = text.lastIndexOf('\n', idx) + 1;
+  const lineEnd = text.indexOf('\n', idx);
+  let hay = text.slice(Math.max(0, idx - 60), idx + q.length + 80);
+  try {
+    const found = findString(JSON.parse(text.slice(lineStart, lineEnd < 0 ? undefined : lineEnd)), q);
+    if (found) {
+      const i = found.toLowerCase().indexOf(q);
+      hay = found.slice(Math.max(0, i - 60), i + q.length + 80);
+    }
+  } catch { /* fall back to raw slice */ }
+  return hay.replace(/\\[nrt]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function findString(v, q) {
+  if (typeof v === 'string') return v.toLowerCase().includes(q) ? v : null;
+  if (v && typeof v === 'object') {
+    for (const x of Object.values(v)) {
+      const r = findString(x, q);
+      if (r) return r;
+    }
+  }
+  return null;
+}
+
+// Moves the transcript (and any sidechain folder) into the agent's ccnav-archive, keeping the
+// path it had under the sessions root, so moving it back restores the session.
+export function archiveSession(session) {
+  const move = (from) => {
+    if (!fs.existsSync(from)) return;
+    const to = path.join(session.archiveRoot, path.relative(session.root, from));
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    try { fs.renameSync(from, to); } catch {
+      fs.cpSync(from, to, { recursive: true });
+      fs.rmSync(from, { recursive: true, force: true });
+    }
+  };
+  move(session.file);
+  for (const extra of session.extraPaths || []) move(extra);
+}
+
+// Written for the shell wrapper function so the calling shell can cd afterwards.
+export function reportCwd(dir) {
+  const file = process.env.CCNAV_CWD_FILE;
+  if (file) try { fs.writeFileSync(file, dir, 'utf8'); } catch { /* ignore */ }
+}

package/src/app.mjs

@@ -0,0 +1,313 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import { Box, Text, useApp, useInput, useStdout } from 'ink';
+import { AGENTS, ago, humanSize, providerOf } from './sessions.mjs';
+import { archiveSession, copyToClipboard, isMaybeLive, openFolder, openInNewTab, searchTranscript } from './actions.mjs';
+
+const h = React.createElement;
+
+const SORTS = [
+  { key: 'lastUsed', label: 'last used', fn: (a, b) => b.lastUsed - a.lastUsed },
+  { key: 'created', label: 'created', fn: (a, b) => b.created - a.created },
+  { key: 'size', label: 'size', fn: (a, b) => b.size - a.size },
+  { key: 'project', label: 'directory name', fn: (a, b) => a.cwd.toLowerCase().localeCompare(b.cwd.toLowerCase()) || b.lastUsed - a.lastUsed },
+];
+
+const pad = (s, n) => {
+  s = String(s ?? '');
+  return s.length > n ? s.slice(0, Math.max(0, n - 1)) + '…' : s.padEnd(n);
+};
+const oneLine = s => String(s || '').replace(/\s+/g, ' ').trim();
+const keyOf = s => `${s.agent}:${s.id}`;
+const DAY = 86400 * 1000;
+
+// mode: list | filter | confirm-archive | prune-days | confirm-prune
+export function App({ sessions: initialSessions, onChoose, passthrough = [] }) {
+  const { exit } = useApp();
+  const { stdout } = useStdout();
+  const width = stdout?.columns || 120;
+  const height = stdout?.rows || 30;
+
+  const [sessions, setSessions] = useState(initialSessions);
+  const [cursor, setCursor] = useState(0);
+  const [sortIdx, setSortIdx] = useState(0);
+  const [filter, setFilter] = useState('');
+  const [mode, setMode] = useState('list');
+  const [deep, setDeep] = useState(false);
+  const [deepHits, setDeepHits] = useState(null); // Map id -> snippet, for the last deep query
+  const [searching, setSearching] = useState(false);
+  const [showScratch, setShowScratch] = useState(false);
+  const [agentIdx, setAgentIdx] = useState(0); // 0 = all agents, then one per agent
+  const [message, setMessage] = useState(null); // { text, color }
+  const [days, setDays] = useState('30');
+
+  // Deep search reads whole transcripts, so it runs once per submitted query rather than per keystroke.
+  useEffect(() => {
+    if (!searching) return;
+    const t = setTimeout(() => {
+      const hits = new Map();
+      for (const s of sessions) {
+        const snip = searchTranscript(s, filter);
+        if (snip) hits.set(keyOf(s), snip);
+      }
+      setDeepHits(hits);
+      setSearching(false);
+      setCursor(0);
+    }, 10);
+    return () => clearTimeout(t);
+  }, [searching]);
+
+  const sorted = useMemo(() => {
+    const q = filter.toLowerCase();
+    const onlyAgent = AGENTS[agentIdx - 1];
+    return sessions
+      .filter(s => showScratch || !s.scratch)
+      .filter(s => !onlyAgent || s.agent === onlyAgent)
+      .filter(s => {
+        if (!q) return true;
+        if (deep) return deepHits ? deepHits.has(keyOf(s)) : true;
+        return [s.title, s.cwd, s.branch, s.firstPrompt, s.lastText, s.id, s.agent]
+          .some(v => v && v.toLowerCase().includes(q));
+      })
+      .sort(SORTS[sortIdx].fn);
+  }, [sessions, filter, sortIdx, showScratch, deep, deepHits, agentIdx]);
+
+  // Group by directory; groups appear in the order of their best session under the current sort,
+  // and `rows` is re-ordered to match so the cursor walks sessions top to bottom.
+  const { rows, groups } = useMemo(() => {
+    const byDir = new Map();
+    for (const s of sorted) {
+      const k = s.cwd.toLowerCase();
+      if (!byDir.has(k)) byDir.set(k, { cwd: s.cwd, exists: s.cwdExists, sessions: [] });
+      byDir.get(k).sessions.push(s);
+    }
+    const groups = [...byDir.values()];
+    return { groups, rows: groups.flatMap(g => g.sessions) };
+  }, [sorted]);
+
+  const pruneTargets = useMemo(() => {
+    const n = Number(days);
+    if (!Number.isFinite(n) || n < 1) return [];
+    return rows.filter(s => Date.now() - s.lastUsed > n * DAY && !isMaybeLive(s));
+  }, [rows, days]);
+
+  const sel = rows[Math.min(cursor, rows.length - 1)];
+  const listHeight = Math.max(4, height - 13);
+
+  // Display lines: a (possibly wrapping) header per directory, then its sessions.
+  const items = useMemo(() => {
+    const out = [];
+    let i = 0;
+    for (const g of groups) {
+      const label = `▾ ${g.cwd}  (${g.sessions.length}${g.exists ? '' : ', missing'})`;
+      out.push({ kind: 'dir', group: g, label, lines: Math.max(1, Math.ceil(label.length / Math.max(20, width))) });
+      for (const s of g.sessions) out.push({ kind: 'session', session: s, index: i++, lines: 1 });
+    }
+    return out;
+  }, [groups, width]);
+
+  // Pick a window of items that fits listHeight lines, keeping the cursor roughly centred.
+  const visible = useMemo(() => {
+    let ci = items.findIndex(it => it.kind === 'session' && it.index === cursor);
+    if (ci < 0) ci = 0;
+    if (!items.length) return [];
+    let start = ci, end = ci + 1, used = items[ci].lines;
+    const up = limit => { while (start > 0 && used + items[start - 1].lines <= limit) used += items[--start].lines; };
+    const down = () => { while (end < items.length && used + items[end].lines <= listHeight) used += items[end++].lines; };
+    up(Math.floor(listHeight / 2));
+    down();
+    up(listHeight);
+    const win = items.slice(start, end);
+    // Pin the directory header when the window starts mid-group.
+    if (win[0]?.kind === 'session') {
+      const hdrIdx = items.slice(0, start).findLastIndex(it => it.kind === 'dir');
+      const hdr = { ...items[hdrIdx], label: items[hdrIdx].label + ' (cont.)' };
+      let spare = listHeight - used;
+      while (spare < hdr.lines && win.length > 1 && win[win.length - 1] !== items[ci]) spare += win.pop().lines;
+      while (spare < hdr.lines && win.length > 1) spare += win.shift().lines;
+      if (spare >= hdr.lines) win.unshift(hdr);
+    }
+    return win;
+  }, [items, cursor, listHeight]);
+
+  const flash = (text, color = 'green') => setMessage({ text, color });
+
+  const requireDir = () => {
+    if (sel.cwdExists) return true;
+    flash(`Directory no longer exists: ${sel.cwd}`, 'red');
+    return false;
+  };
+
+  const choose = action => {
+    if (!sel || !requireDir()) return;
+    onChoose({ action, session: sel });
+    exit();
+  };
+
+  const removeSessions = gone => {
+    const ids = new Set(gone.map(keyOf));
+    setSessions(list => list.filter(s => !ids.has(keyOf(s))));
+    setCursor(c => Math.max(0, Math.min(c, rows.length - 1 - gone.length)));
+  };
+
+  const archive = targets => {
+    const done = [];
+    for (const s of targets) {
+      try { archiveSession(s); done.push(s); } catch (e) { flash(`Archive failed for ${s.id}: ${e.message}`, 'red'); }
+    }
+    removeSessions(done);
+    if (done.length) flash(`Archived ${done.length} session${done.length === 1 ? '' : 's'} to the agent's ccnav-archive folder`);
+  };
+
+  useInput((input, key) => {
+    setMessage(null);
+
+    if (mode === 'filter') {
+      if (key.escape) { setMode('list'); setFilter(''); setDeepHits(null); return; }
+      if (key.tab) { setDeep(d => !d); setDeepHits(null); return; }
+      if (key.return) { setMode('list'); if (deep && filter) setSearching(true); return; }
+      if (key.backspace || key.delete) { setFilter(f => f.slice(0, -1)); setDeepHits(null); setCursor(0); return; }
+      if (input && !key.ctrl && !key.meta) { setFilter(f => f + input); setDeepHits(null); setCursor(0); }
+      return;
+    }
+
+    if (mode === 'confirm-archive') {
+      if (input === 'y' || input === 'Y') archive([sel]);
+      setMode('list');
+      return;
+    }
+
+    if (mode === 'prune-days') {
+      if (key.escape) { setMode('list'); return; }
+      if (key.return) { setMode(pruneTargets.length ? 'confirm-prune' : 'list'); if (!pruneTargets.length) flash('Nothing that old.', 'yellow'); return; }
+      if (key.backspace || key.delete) { setDays(d => d.slice(0, -1)); return; }
+      if (/^\d$/.test(input)) setDays(d => (d + input).slice(0, 4));
+      return;
+    }
+
+    if (mode === 'confirm-prune') {
+      if (input === 'y' || input === 'Y') archive(pruneTargets);
+      setMode('list');
+      return;
+    }
+
+    const move = d => setCursor(c => Math.max(0, Math.min(rows.length - 1, c + d)));
+    if (key.upArrow || input === 'k') move(-1);
+    else if (key.downArrow || input === 'j') move(1);
+    else if (key.pageUp) move(-listHeight);
+    else if (key.pageDown) move(listHeight);
+    else if (input === 'g') setCursor(0);
+    else if (input === 'G') setCursor(rows.length - 1);
+    else if (input === ']' || input === '[') {
+      // Jump to the first session of the next / previous directory.
+      const starts = [];
+      let n = 0;
+      for (const g of groups) { starts.push(n); n += g.sessions.length; }
+      const cur = starts.findLastIndex(st => st <= cursor);
+      const target = input === ']' ? starts[cur + 1] : (cursor > starts[cur] ? starts[cur] : starts[cur - 1]);
+      if (target !== undefined) setCursor(target);
+    }
+    else if (key.return) choose('resume');
+    else if (input === 'f') choose('fork');
+    else if (input === 'n') choose('new');
+    else if (input === 't' && sel && requireDir()) {
+      try {
+        const p = providerOf(sel);
+        const where = openInNewTab(p.command, sel.cwd, p.launchArgs('resume', sel, passthrough), oneLine(sel.title) || sel.id);
+        flash(`Opened "${oneLine(sel.title) || sel.id}" in a new ${where}`);
+      } catch (e) { flash(`Could not open a new tab: ${e.message}`, 'red'); }
+    }
+    else if (input === 'o' && sel && requireDir()) { openFolder(sel.cwd); flash(`Opened ${sel.cwd}`); }
+    else if (input === 'c' && sel) {
+      try { copyToClipboard(sel.id); flash(`Copied ${sel.id}`); } catch (e) { flash(`Copy failed: ${e.message}`, 'red'); }
+    }
+    else if (input === 'x' && sel) {
+      if (isMaybeLive(sel)) flash('Used in the last 10 minutes; it may still be open. Not archiving.', 'yellow');
+      else setMode('confirm-archive');
+    }
+    else if (input === 'X') setMode('prune-days');
+    else if (input === '/') setMode('filter');
+    else if (input === 's') { setSortIdx(i => (i + 1) % SORTS.length); setCursor(0); }
+    else if (key.tab) { setAgentIdx(i => (i + 1) % (AGENTS.length + 1)); setCursor(0); }
+    else if (input === 'a') { setShowScratch(v => !v); setCursor(0); }
+    else if (key.escape && filter) { setFilter(''); setDeepHits(null); setCursor(0); }
+    else if (input === 'q' || key.escape) exit();
+  });
+
+  const cTitle = Math.max(20, width - 4 - 2 - 14 - 10 - 10 - 7 - 5);
+  const header = pad('TITLE', cTitle) + ' ' + pad('BRANCH', 14) + ' '
+    + pad('CREATED', 10) + ' ' + pad('LAST USED', 10) + ' ' + pad('SIZE', 7);
+  const hiddenScratch = showScratch ? 0 : sessions.filter(s => s.scratch).length;
+  const agentCounts = AGENTS
+    .map(a => [a, rows.filter(s => s.agent === a).length])
+    .filter(([, n]) => n)
+    .map(([a, n]) => ` · ${n} ${a}`).join('');
+
+  const filterLine = h(Text, { wrap: 'truncate' },
+    h(Text, { color: mode === 'filter' ? 'yellow' : 'gray' }, deep ? 'full-text / ' : 'filter / '),
+    filter || (mode === 'filter' ? '' : h(Text, { dimColor: true }, 'press / to filter')),
+    mode === 'filter' ? h(Text, { inverse: true }, ' ') : null,
+    mode === 'filter' ? h(Text, { dimColor: true }, deep
+      ? '   tab: titles only · enter: search all transcripts'
+      : '   tab: search full transcripts') : null,
+    searching ? h(Text, { color: 'yellow' }, '   searching…') : null,
+    deep && deepHits && !searching ? h(Text, { dimColor: true }, `   ${deepHits.size} transcripts match`) : null,
+  );
+
+  let prompt = null;
+  if (mode === 'confirm-archive' && sel) {
+    prompt = h(Text, { color: 'yellow' }, `Archive "${oneLine(sel.title) || sel.id}"? It moves to the ${sel.agent} ccnav-archive folder and can be moved back. (y/N)`);
+  } else if (mode === 'prune-days') {
+    prompt = h(Text, { color: 'yellow' }, 'Archive sessions not used in the last ', h(Text, { inverse: true }, days || ' '),
+      ` days  →  ${pruneTargets.length} match (of those listed). enter to continue, esc to cancel`);
+  } else if (mode === 'confirm-prune') {
+    prompt = h(Text, { color: 'yellow' }, `Archive ${pruneTargets.length} sessions not used in ${days} days? (y/N)`);
+  }
+
+  const snippet = sel && deep && deepHits?.get(keyOf(sel));
+
+  return h(Box, { flexDirection: 'column', width },
+    h(Box, null,
+      h(Text, { bold: true, color: 'cyan' }, 'ccnav'),
+      h(Text, { dimColor: true },
+        ` ${rows.length} sessions${agentCounts} · sorted by ${SORTS[sortIdx].label}`
+        + (AGENTS[agentIdx - 1] ? ` · ${AGENTS[agentIdx - 1]} only (tab)` : '')
+        + (hiddenScratch ? ` · ${hiddenScratch} desktop scratch hidden (a)` : '')),
+    ),
+    filterLine,
+    h(Text, { bold: true, dimColor: true }, '      ' + header),
+    ...visible.map(it => {
+      if (it.kind === 'dir') {
+        return h(Text, { key: 'dir:' + it.group.cwd, bold: true, color: it.group.exists ? 'cyan' : 'red', wrap: 'wrap' }, it.label);
+      }
+      const s = it.session;
+      const p = providerOf(s);
+      const active = it.index === cursor;
+      const line = pad(oneLine(s.title || s.firstPrompt) || '(untitled)', cTitle) + ' '
+        + pad(s.branch, 14) + ' ' + pad(ago(s.created), 10) + ' ' + pad(ago(s.lastUsed), 10) + ' '
+        + pad(humanSize(s.size), 7);
+      return h(Text, { key: keyOf(s), inverse: active, color: s.cwdExists ? undefined : 'red', wrap: 'truncate' },
+        (active ? '  › ' : '    '),
+        h(Text, { color: s.cwdExists ? p.color : 'red' }, p.glyph + ' '),
+        line);
+    }),
+    rows.length === 0 ? h(Text, { dimColor: true }, searching ? '  searching…' : '  no sessions match') : null,
+    h(Box, { marginTop: 1, flexDirection: 'column', borderStyle: 'round', borderColor: 'gray', paddingX: 1 },
+      sel ? [
+        h(Text, { key: 'p', wrap: 'truncate' }, h(Text, { dimColor: true }, 'dir    '), sel.cwd,
+          sel.cwdExists ? '' : h(Text, { color: 'red' }, '  (missing)')),
+        h(Text, { key: 'i', wrap: 'truncate' }, h(Text, { dimColor: true }, 'id     '), sel.id,
+          h(Text, { dimColor: true }, `  ·  ${sel.agent}${sel.origin === 'desktop' ? ' (desktop/IDE)' : ''}`
+            + `${sel.version ? ' ' + sel.version : ''}`
+            + `  ·  started ${sel.created.toLocaleString()}  ·  last ${sel.lastUsed.toLocaleString()}`)),
+        h(Text, { key: 'f', wrap: 'truncate' }, h(Text, { dimColor: true }, 'first  '), oneLine(sel.firstPrompt)),
+        snippet
+          ? h(Text, { key: 'm', wrap: 'truncate' }, h(Text, { dimColor: true }, 'match  '), h(Text, { color: 'yellow' }, '…' + snippet + '…'))
+          : h(Text, { key: 'l', wrap: 'truncate' }, h(Text, { dimColor: true }, pad(sel.lastLabel || 'last', 7)), oneLine(sel.lastText)),
+      ] : h(Text, { dimColor: true }, 'nothing selected'),
+    ),
+    prompt,
+    message ? h(Text, { color: message.color, wrap: 'truncate' }, message.text) : null,
+    h(Text, { dimColor: true, wrap: 'truncate' },
+      '↑↓ move  [ ] prev/next dir  tab agent  enter resume  t new tab  f fork  n new here  o open dir  c copy id  / filter  s sort  x archive  X archive old  a scratch  q quit'),
+  );
+}

package/src/jsonl.mjs

@@ -0,0 +1,45 @@
+// Shared JSONL reading: transcripts reach tens of MB, so only the ends are read.
+import fs from 'node:fs';
+
+export const HEAD_BYTES = 256 * 1024;
+export const TAIL_BYTES = 256 * 1024;
+
+function readSlice(fd, start, length) {
+  const buf = Buffer.alloc(length);
+  const n = fs.readSync(fd, buf, 0, length, start);
+  return buf.subarray(0, n).toString('utf8');
+}
+
+export function parseLines(text, { dropFirst = false, dropLast = false } = {}) {
+  const lines = text.split('\n');
+  if (dropFirst) lines.shift();
+  if (dropLast) lines.pop();
+  const out = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* partial or corrupt line */ }
+  }
+  return out;
+}
+
+// Returns { stat, head, tail }; tail === head when the file fits in one read.
+export function readEnds(file) {
+  const stat = fs.statSync(file);
+  const fd = fs.openSync(file, 'r');
+  try {
+    const headLen = Math.min(HEAD_BYTES, stat.size);
+    const head = parseLines(readSlice(fd, 0, headLen), { dropLast: headLen < stat.size });
+    const tailStart = Math.max(0, stat.size - TAIL_BYTES);
+    const tail = tailStart > headLen
+      ? parseLines(readSlice(fd, tailStart, stat.size - tailStart), { dropFirst: true })
+      : head;
+    return { stat, head, tail };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Text a person typed, with injected <system-reminder>-style wrappers removed.
+export function humanText(text) {
+  return String(text || '').replace(/<([\w-]+)[^>]*>[\s\S]*?<\/\1>/g, '').trim();
+}

package/src/platform.mjs

@@ -0,0 +1,194 @@
+// Everything that differs between Windows, macOS and Linux lives here.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+
+export const IS_WIN = process.platform === 'win32';
+export const IS_MAC = process.platform === 'darwin';
+
+const has = cmd => IS_WIN
+  ? spawnSync('where', [cmd], { stdio: 'ignore' }).status === 0
+  : spawnSync('sh', ['-c', `command -v ${cmd}`], { stdio: 'ignore' }).status === 0;
+
+// POSIX single-quote escaping for building `sh -c` / AppleScript command lines.
+const shq = s => `'${String(s).replace(/'/g, `'\\''`)}'`;
+// Windows command lines: quote args with spaces, strip embedded quotes (args are UUIDs and flags).
+const winq = s => /[\s"]/.test(s) ? `"${String(s).replace(/"/g, '')}"` : s;
+const osaString = s => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+const INSTALL_HINT = {
+  claude: 'npm install -g @anthropic-ai/claude-code',
+  codex: 'npm install -g @openai/codex',
+};
+
+// Runs the agent in the foreground with the session's directory as cwd; resolves with its exit code.
+export function launchAgent(cmd, cwd, args) {
+  return new Promise(resolve => {
+    // On Windows these are npm .cmd shims, which need a shell; elsewhere spawn them directly.
+    const child = IS_WIN
+      ? spawn([cmd, ...args.map(winq)].join(' '), { cwd, stdio: 'inherit', shell: true })
+      : spawn(cmd, args, { cwd, stdio: 'inherit' });
+    child.on('error', e => {
+      console.error(e.code === 'ENOENT'
+        ? `${cmd} was not found on PATH.${INSTALL_HINT[cmd] ? ` Install it: ${INSTALL_HINT[cmd]}` : ''}`
+        : `could not start ${cmd}: ${e.message}`);
+      resolve(127);
+    });
+    child.on('exit', code => resolve(code ?? 0));
+  });
+}
+
+// Opens a new terminal tab (or window) in `cwd` running `cmd` with `args`. Throws if nothing worked.
+export function openInNewTab(cmd, cwd, args, title = cmd) {
+  const run = (cmd, argv) => {
+    const r = spawnSync(cmd, argv, { stdio: 'ignore' });
+    if (r.error || r.status !== 0) throw new Error(`${cmd} failed${r.error ? `: ${r.error.message}` : ` (exit ${r.status})`}`);
+  };
+
+  if (IS_WIN) {
+    const argv = ['-w', '0', 'new-tab', '--title', title.replace(/[;"]/g, ' ').slice(0, 40), '-d', cwd,
+      'pwsh', '-NoExit', '-Command', cmd, ...args];
+    // wt.exe is an app execution alias, which needs a shell to launch reliably; it returns immediately.
+    const r = spawnSync(['wt.exe', ...argv.map(winq)].join(' '), { shell: true, stdio: 'ignore', windowsHide: true });
+    if (r.error || r.status !== 0) throw new Error(r.error?.message || `wt.exe exited with ${r.status}`);
+    return 'Windows Terminal tab';
+  }
+
+  const shellCmd = `cd ${shq(cwd)} && ${cmd} ${args.map(shq).join(' ')}`;
+  const term = process.env.TERM_PROGRAM || '';
+
+  if (term === 'WezTerm' && has('wezterm')) {
+    run('wezterm', ['cli', 'spawn', '--cwd', cwd, '--', cmd, ...args]);
+    return 'WezTerm tab';
+  }
+  if (process.env.KITTY_WINDOW_ID && has('kitty')) {
+    run('kitty', ['@', 'launch', '--type=tab', '--cwd', cwd, cmd, ...args]);
+    return 'kitty tab';
+  }
+  if (IS_MAC) {
+    if (term === 'iTerm.app') {
+      run('osascript', [
+        '-e', 'tell application "iTerm" to tell current window to create tab with default profile',
+        '-e', `tell application "iTerm" to tell current session of current window to write text ${osaString(shellCmd)}`,
+      ]);
+      return 'iTerm tab';
+    }
+    // Terminal.app (and anything else): a new Terminal window. Real tabs would need Accessibility permission.
+    run('osascript', ['-e', `tell application "Terminal" to do script ${osaString(shellCmd)}`,
+      '-e', 'tell application "Terminal" to activate']);
+    return 'Terminal window';
+  }
+  if (has('gnome-terminal')) {
+    run('gnome-terminal', ['--tab', `--working-directory=${cwd}`, '--', cmd, ...args]);
+    return 'GNOME Terminal tab';
+  }
+  if (has('konsole')) {
+    run('konsole', ['--new-tab', '--workdir', cwd, '-e', cmd, ...args]);
+    return 'Konsole tab';
+  }
+  throw new Error('no supported terminal found (Windows Terminal, iTerm2, Terminal.app, WezTerm, kitty, GNOME Terminal, Konsole)');
+}
+
+export function openFolder(dir) {
+  const cmd = IS_WIN ? 'explorer.exe' : IS_MAC ? 'open' : 'xdg-open';
+  const child = spawn(cmd, [dir], { detached: true, stdio: 'ignore' });
+  child.on('error', () => {});
+  child.unref();
+}
+
+export function copyToClipboard(text) {
+  const candidates = IS_WIN ? [['clip', []]]
+    : IS_MAC ? [['pbcopy', []]]
+    : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+  for (const [cmd, argv] of candidates) {
+    const r = spawnSync(cmd, argv, { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
+    if (!r.error && r.status === 0) return;
+  }
+  throw new Error('no clipboard tool found');
+}
+
+// ---- shell integration: a wrapper function that cds into the directory ccnav reports ----
+
+const BEGIN = '# >>> ccnav >>>';
+const END = '# <<< ccnav <<<';
+
+const POWERSHELL_FN = `
+# Wraps the ccnav npm shim so this shell ends up in the chosen session's directory.
+function ccnav {
+    $shim = Join-Path $env:APPDATA 'npm\\ccnav.ps1'
+    if (-not (Test-Path -LiteralPath $shim)) { Write-Warning 'ccnav is not installed on this machine'; return }
+    $cwdFile = [IO.Path]::GetTempFileName()
+    $env:CCNAV_CWD_FILE = $cwdFile
+    try { & $shim @args }
+    finally {
+        Remove-Item Env:CCNAV_CWD_FILE -ErrorAction Ignore
+        $dir = Get-Content -LiteralPath $cwdFile -Raw -ErrorAction Ignore
+        Remove-Item -LiteralPath $cwdFile -ErrorAction Ignore
+        if ($dir -and (Test-Path -LiteralPath $dir.Trim())) { Set-Location -LiteralPath $dir.Trim() }
+    }
+}
+`;
+
+// Works in both bash and zsh. `command` skips the function; the subshell check avoids finding it too.
+const POSIX_FN = `
+# Wraps the ccnav binary so this shell ends up in the chosen session's directory.
+ccnav() {
+  if ! (unset -f ccnav; command -v ccnav >/dev/null 2>&1); then
+    echo "ccnav: not installed on this machine" >&2; return 1
+  fi
+  local f rc dir
+  f=$(mktemp "\${TMPDIR:-/tmp}/ccnav.XXXXXX") || return 1
+  CCNAV_CWD_FILE="$f" command ccnav "$@"
+  rc=$?
+  dir=$(cat "$f" 2>/dev/null); rm -f "$f"
+  if [ -n "$dir" ] && [ -d "$dir" ]; then cd "$dir"; fi
+  return $rc
+}
+`;
+
+const FISH_FN = `
+function ccnav --description 'Resume a Claude Code or Codex session in its directory'
+    if not command -q ccnav
+        echo "ccnav: not installed on this machine" >&2; return 1
+    end
+    set -l f (mktemp)
+    env CCNAV_CWD_FILE=$f command ccnav $argv
+    set -l rc $status
+    set -l dir (cat $f 2>/dev/null); rm -f $f
+    if test -n "$dir"; and test -d "$dir"; cd $dir; end
+    return $rc
+end
+`;
+
+function shellTarget() {
+  if (IS_WIN) {
+    const r = spawnSync('pwsh', ['-NoProfile', '-Command', '$PROFILE'], { encoding: 'utf8' });
+    const file = r.stdout?.trim() || path.join(os.homedir(), 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1');
+    return { shell: 'powershell', file, body: POWERSHELL_FN };
+  }
+  const shell = path.basename(process.env.SHELL || (IS_MAC ? 'zsh' : 'bash'));
+  if (shell === 'fish') {
+    return { shell, file: path.join(os.homedir(), '.config', 'fish', 'functions', 'ccnav.fish'), body: FISH_FN };
+  }
+  if (shell === 'zsh') {
+    return { shell, file: path.join(process.env.ZDOTDIR || os.homedir(), '.zshrc'), body: POSIX_FN };
+  }
+  // macOS login shells read .bash_profile; Linux interactive shells read .bashrc.
+  return { shell: 'bash', file: path.join(os.homedir(), IS_MAC ? '.bash_profile' : '.bashrc'), body: POSIX_FN };
+}
+
+// Idempotent: replaces an existing ccnav block instead of appending a second one.
+export function installShellFunction() {
+  const { shell, file, body } = shellTarget();
+  const block = `${BEGIN}${body}${END}`;
+  const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const re = new RegExp(`${BEGIN}[\\s\\S]*?${END}`);
+  const next = re.test(current)
+    ? current.replace(re, () => block)
+    : current.replace(/\s*$/, '') + (current ? '\n\n' : '') + block + '\n';
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, next, 'utf8');
+  const reload = shell === 'powershell' ? '. $PROFILE' : shell === 'fish' ? 'open a new fish shell' : `source ${file.replace(os.homedir(), '~')}`;
+  return { shell, file, reload };
+}

package/src/providers/claude.mjs

@@ -0,0 +1,90 @@
+// Claude Code sessions: ~/.claude/projects/<encoded-dir>/<session-id>.jsonl
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { humanText, readEnds } from '../jsonl.mjs';
+
+export const agent = 'claude';
+export const command = 'claude';
+export const glyph = '◆';
+export const color = 'cyan';
+
+export const HOME_DIR = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+export const SESSIONS_ROOT = path.join(HOME_DIR, 'projects');
+export const ARCHIVE_ROOT = path.join(HOME_DIR, 'ccnav-archive');
+
+function promptText(r) {
+  if (r.type !== 'user' || r.isMeta || r.isSidechain) return '';
+  const c = r.message?.content;
+  const text = typeof c === 'string' ? c
+    : Array.isArray(c) ? c.filter(b => b.type === 'text').map(b => b.text).join(' ') : '';
+  return humanText(text);
+}
+
+export function readSession(file) {
+  const { stat, head, tail } = readEnds(file);
+  const firstMsg = head.find(r => r.cwd && r.timestamp);
+  const firstPrompt = head.map(promptText).find(Boolean);
+  let title, lastPrompt, lastTs, bridge, lastCwd, branch;
+  for (const r of tail) {
+    if (r.type === 'ai-title' && r.aiTitle) title = r.aiTitle;
+    if (r.type === 'custom-title' && r.customTitle) title = r.customTitle;
+    if (r.type === 'last-prompt' && r.lastPrompt) lastPrompt = r.lastPrompt;
+    if (r.timestamp) lastTs = r.timestamp;
+    if (r.cwd) lastCwd = r.cwd;
+    if (r.gitBranch) branch = r.gitBranch;
+  }
+  for (const r of head) if (r.type === 'bridge-session' && r.bridgeSessionId) bridge = r.bridgeSessionId;
+  if (!title) for (const r of head) if (r.type === 'ai-title' && r.aiTitle) title = r.aiTitle;
+
+  const cwd = firstMsg?.cwd || lastCwd;
+  if (!cwd) return null; // no conversation ever happened
+
+  const id = path.basename(file, '.jsonl');
+  return {
+    agent, id, file,
+    // Subagent sidechains live in a folder named after the session; archive it alongside.
+    extraPaths: [path.join(path.dirname(file), id)],
+    root: SESSIONS_ROOT,
+    archiveRoot: ARCHIVE_ROOT,
+    cwd,
+    cwdExists: fs.existsSync(cwd),
+    branch: (b => b === 'HEAD' ? '' : b)(branch || firstMsg?.gitBranch || ''),
+    version: firstMsg?.version || '',
+    origin: 'cli',
+    title: title || '',
+    firstPrompt: firstPrompt || '',
+    lastText: lastPrompt || '',
+    lastLabel: 'last',
+    bridgeSessionId: bridge || '',
+    created: new Date(firstMsg?.timestamp || stat.birthtime),
+    lastUsed: lastTs ? new Date(Math.max(new Date(lastTs), stat.mtime)) : stat.mtime,
+    size: stat.size,
+    // Claude Desktop scratch folders: %APPDATA%\Claude\... on Windows, ~/Library/Application Support/Claude/... on macOS.
+    scratch: /[\\/]Claude[\\/]scratch-workspaces[\\/]/i.test(cwd),
+  };
+}
+
+// Top-level *.jsonl only: <sessionId>/ subdirectories hold subagent sidechains.
+export function listSessions() {
+  if (!fs.existsSync(SESSIONS_ROOT)) return [];
+  const out = [];
+  for (const dir of fs.readdirSync(SESSIONS_ROOT, { withFileTypes: true })) {
+    if (!dir.isDirectory()) continue;
+    const projectDir = path.join(SESSIONS_ROOT, dir.name);
+    for (const f of fs.readdirSync(projectDir)) {
+      if (!f.endsWith('.jsonl')) continue;
+      try {
+        const s = readSession(path.join(projectDir, f));
+        if (s) out.push(s);
+      } catch { /* unreadable file */ }
+    }
+  }
+  return out;
+}
+
+export function launchArgs(action, session, passthrough = []) {
+  if (action === 'fork') return ['--resume', session.id, '--fork-session', ...passthrough];
+  if (action === 'new') return [...passthrough];
+  return ['--resume', session.id, ...passthrough];
+}

package/src/providers/codex.mjs

@@ -0,0 +1,110 @@
+// Codex CLI sessions: ~/.codex/sessions/YYYY/MM/DD/rollout-<time>-<uuid>.jsonl
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { humanText, readEnds } from '../jsonl.mjs';
+
+export const agent = 'codex';
+export const command = 'codex';
+export const glyph = '●';
+export const color = 'green';
+
+export const HOME_DIR = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+export const SESSIONS_ROOT = path.join(HOME_DIR, 'sessions');
+export const ARCHIVE_ROOT = path.join(HOME_DIR, 'ccnav-archive');
+const INDEX_FILE = path.join(HOME_DIR, 'session_index.jsonl');
+
+// session_index.jsonl names about half the sessions; read it once per listing.
+function readIndex() {
+  const map = new Map();
+  let text;
+  try { text = fs.readFileSync(INDEX_FILE, 'utf8'); } catch { return map; }
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const { id, thread_name, updated_at } = JSON.parse(line);
+      if (id) map.set(id, { title: thread_name || '', updatedAt: updated_at ? new Date(updated_at) : null });
+    } catch { /* skip */ }
+  }
+  return map;
+}
+
+const textOf = content => (Array.isArray(content) ? content : [])
+  .filter(c => c.type === 'input_text' || c.type === 'text' || c.type === 'output_text')
+  .map(c => c.text).join(' ');
+
+export function readSession(file, index = readIndex()) {
+  const { stat, head, tail } = readEnds(file);
+  const meta = head.find(r => r.type === 'session_meta')?.payload;
+  if (!meta?.cwd) return null;
+
+  const firstPrompt = head
+    .filter(r => r.type === 'response_item' && r.payload?.type === 'message' && r.payload.role === 'user')
+    .map(r => humanText(textOf(r.payload.content)))
+    .find(Boolean) || '';
+
+  let lastText = '', lastTs;
+  for (const r of tail) {
+    if (r.timestamp) lastTs = r.timestamp;
+    const p = r.payload;
+    if (p?.type === 'task_complete' && p.last_agent_message) lastText = p.last_agent_message;
+    else if (p?.type === 'agent_message' && p.message) lastText = p.message;
+  }
+
+  const id = meta.session_id || meta.id;
+  const indexed = index.get(id);
+  const stamps = [stat.mtime, lastTs && new Date(lastTs), indexed?.updatedAt].filter(Boolean);
+  // Desktop and IDE sessions are stored here too; the CLI can still resume them.
+  const origin = meta.source === 'cli' || /cli/i.test(meta.originator || '') ? 'cli' : 'desktop';
+
+  return {
+    agent, id, file,
+    extraPaths: [],
+    root: SESSIONS_ROOT,
+    archiveRoot: ARCHIVE_ROOT,
+    cwd: meta.cwd,
+    cwdExists: fs.existsSync(meta.cwd),
+    branch: '',
+    version: meta.cli_version || '',
+    origin,
+    // A session spawned by another session, like a Claude sidechain.
+    subagent: !!(meta.source && typeof meta.source === 'object' && meta.source.subagent),
+    title: indexed?.title || '',
+    firstPrompt,
+    lastText: humanText(lastText),
+    lastLabel: 'reply',
+    created: new Date(meta.timestamp || head[0]?.timestamp || stat.birthtime),
+    lastUsed: new Date(Math.max(...stamps.map(Number))),
+    size: stat.size,
+    scratch: false,
+  };
+}
+
+// sessions/YYYY/MM/DD/*.jsonl
+export function listSessions() {
+  if (!fs.existsSync(SESSIONS_ROOT)) return [];
+  const index = readIndex();
+  const out = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory() && depth < 3) walk(p, depth + 1);
+      else if (e.isFile() && e.name.endsWith('.jsonl')) {
+        try {
+          const s = readSession(p, index);
+          if (s && !s.subagent) out.push(s);
+        } catch { /* unreadable file */ }
+      }
+    }
+  };
+  walk(SESSIONS_ROOT, 0);
+  return out;
+}
+
+export function launchArgs(action, session, passthrough = []) {
+  if (action === 'fork') return ['fork', session.id, ...passthrough];
+  if (action === 'new') return [...passthrough];
+  return ['resume', session.id, ...passthrough];
+}

package/src/sessions.mjs

@@ -0,0 +1,40 @@
+import os from 'node:os';
+import * as claude from './providers/claude.mjs';
+import * as codex from './providers/codex.mjs';
+
+export const PROVIDERS = { claude, codex };
+export const AGENTS = Object.keys(PROVIDERS);
+
+// Both agents' sessions in one list, newest use first.
+export function listSessions({ agents = AGENTS } = {}) {
+  const out = [];
+  for (const name of agents) {
+    try { out.push(...PROVIDERS[name].listSessions()); } catch { /* provider not installed */ }
+  }
+  return out.sort((a, b) => b.lastUsed - a.lastUsed);
+}
+
+export function providerOf(session) {
+  return PROVIDERS[session.agent] || PROVIDERS.claude;
+}
+
+export function ago(date, now = Date.now()) {
+  const s = Math.max(0, (now - date) / 1000);
+  if (s < 60) return 'just now';
+  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`;
+  if (s < 86400 * 365) return `${Math.floor(s / 86400 / 30)}mo ago`;
+  return `${Math.floor(s / 86400 / 365)}y ago`;
+}
+
+export function humanSize(n) {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 ** 2) return `${Math.round(n / 1024)}K`;
+  return `${(n / 1024 ** 2).toFixed(1)}M`;
+}
+
+export function shortPath(p) {
+  const home = os.homedir();
+  return p.toLowerCase().startsWith(home.toLowerCase()) ? '~' + p.slice(home.length) : p;
+}