Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* session-discovery — find resumable Claude Code sessions, grouped by worktree.
*
* Claude Code stores one JSONL transcript per session at
* `~/.claude/projects/<slugged-cwd>/<session-uuid>.jsonl`. The FILENAME is the id
* `claude --resume` takes, so nothing here has to parse a file to know what to resume.
*
* SCALE IS THE DESIGN CONSTRAINT, and it is not hypothetical. MEASURED on this machine:
* 5,656 transcripts across 219 project directories, 2.57 GB in total, the largest single
* file 73.5 MB. Reading transcripts to build a list is therefore off the table — it
* would be gigabytes of I/O to draw one screen. Two rules follow, and everything below
* is shaped by them:
*
* 1. THE LIST IS BUILT FROM DIRECTORY NAMES AND `stat` ALONE. Grouping, worktree
* identity and recency all come from the path and the mtime, so opening a
* transcript is never on the path to a rendered row.
* 2. DETAIL IS HYDRATED LAZILY, AND ONLY IN BOUNDED CHUNKS. `hydrateSession` reads a
* 64 KB head and a 128 KB tail with positioned reads — never the middle, never the
* whole file — so a 73 MB transcript costs the same as a 73 KB one.
*/
import { execFile, execFileSync } from "node:child_process";
import { closeSync, openSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
import { basename, join } from "node:path";
import { projectDirNameFor } from "../mcp-session/home-dir.js";
import { claudeConfigDir } from "../mcp-session/parent-session.js";
/** Head bytes scanned for the `entrypoint` marker. See `isAgentSession`. */
const ENTRYPOINT_BYTES = 8192;
/**
* Where Claude Code keeps transcripts: `<config dir>/projects`, the config dir being
* `CLAUDE_CONFIG_DIR`, else `$HOME/.claude` (`claudeConfigDir`, `mcp-session/parent-session.ts`).
*
* Resolved at CALL time from the environment it is given. It used to be a module
* constant built from `os.homedir()`, which is wrong twice: it ignored a
* `CLAUDE_CONFIG_DIR` Claude Code honours, and Bun's `os.homedir()` ignores a `HOME`
* set by a sandbox or launcher, which Claude Code follows. An owner that spawns a child
* under a different environment passes that environment here.
*/
export function projectsDir(env: Record<string, string | undefined> = process.env): string {
return join(claudeConfigDir(env), "projects");
}
/**
* Claude Code's directory name for a working directory: every character outside
* `[A-Za-z0-9]` becomes `-`. MEASURED against real directories —
* `/Users/jack/mag/claudish/.claude/worktrees/x` becomes
* `-Users-jack-mag-claudish--claude-worktrees-x`, the doubled dash being the `/` and
* the `.` of `/.claude` in sequence, and a live run in a cwd named `fresh_cwd.v1`
* created `…-fresh-cwd-v1`: the `_` is replaced too. This used to replace only `/` and
* `.`, so a cwd with `_`, a space or `@` produced a transcript path that did not exist.
*
* ONE rule: this is `projectDirNameFor` (`mcp-session/home-dir.ts`), which also cuts a slug
* over 200 characters and appends Claude Code's hash. `session-events`' `slugFromCwd`
* calls the same function, so no two transcript paths claudish derives can drift apart.
* Callers pass a realpath (`transcriptPathFor` resolves one; git hands out real paths).
*
* The mapping is deliberately NOT inverted anywhere in this file. It is lossy — a `-`
* in the slug could have been any non-alphanumeric character — so un-slugging a path
* would guess. Every real path here comes from git or from the caller instead.
*/
export function slugForPath(absPath: string): string {
return projectDirNameFor(absPath);
}
/**
* Where Claude Code will write the transcript for a session running in `cwd`
* under `sessionUuid`. Both halves are known before the child starts — claudish
* mints the uuid and passes it as `--session-id` — so this is a derivation, not
* a search by mtime.
*
* **The slug is taken from the REALPATH.** Claude Code resolves symlinks before
* slugging, and every other caller here starts from a path git handed it, which
* is already real. A path that came from a user (`work_dir`, `process.cwd()`
* inside a symlinked worktree, anything under macOS `/tmp` → `/private/tmp`)
* has not been resolved, and its raw slug names a directory that does not
* exist. That is exactly how the two silent-success sessions' transcripts were
* declared "missing": they were under the session's own `work_dir`, in a
* project directory nobody thought to look in.
*
* Falls back to the path as given when it cannot be resolved — a cwd that has
* since been deleted should still produce the best guess available, not null.
*
* `projectsRoot` is the CHILD's projects directory: `projectsDir(childEnv)` when the
* child runs under an environment other than this process's.
*/
export function transcriptPathFor(
cwd: string,
sessionUuid: string,
projectsRoot: string = projectsDir()
): string {
let real = cwd;
try {
real = realpathSync(cwd);
} catch {
// Deleted, unreadable, or never existed. The unresolved slug is still the
// right answer whenever no symlink was involved.
}
return join(projectsRoot, slugForPath(real), `${sessionUuid}.jsonl`);
}
/** A resumable session. Fields below `sizeBytes` are absent until `hydrateSession`. */
export interface SessionRow {
/** The UUID `claude --resume` accepts. Taken from the filename. */
id: string;
file: string;
mtimeMs: number;
/**
* When the transcript was CREATED. Free from the same `stat` as `mtimeMs`.
*
* Optional because a row can be built without one (tests, and any future source that
* is not a `stat`), and every reader must treat an absent value as "unknown" rather
* than as "old" — see `findLatestSessionId`, which falls back instead of excluding.
*/
birthtimeMs?: number;
sizeBytes: number;
/** Claude Code's own generated title, the single best label for a session. */
title?: string;
/** The opening user prompt, cleaned of slash-command envelopes. */
firstPrompt?: string;
gitBranch?: string;
/** Display columns of the final user message — "how big was the last thing I said". */
lastMessageChars?: number;
hydrated?: boolean;
/**
* The tail of the conversation, oldest → newest, user and assistant interleaved.
*
* A title says what a session was ABOUT; the last exchange says where it got to, which
* is the thing you actually need to decide whether it is the one to resume.
*/
recentTurns?: Array<{ role: "user" | "assistant"; text: string }>;
/** Whether the deep search for a human turn has already run — see `hydrateConversation`. */
conversationDeepened?: boolean;
/**
* How the session was launched: `cli` for one a human started, `sdk-cli` for one
* driven programmatically. Read during the list pass because it decides whether the
* row is OFFERED at all, and a filter cannot wait for lazy hydration.
* Undefined when the marker was not in the file's first 8 KB.
*/
entrypoint?: string;
}
/**
* Whether this session was machine-driven rather than started by a person.
*
* claudish itself is a prolific source of these: every `team` member, every MCP
* `create_session`, every `-p` one-shot and every e2e test spawns a real Claude Code
* session that lands in the same project directory as your own work. MEASURED across
* this repository: 1,923 of 2,018 transcripts are `sdk-cli` — so 95% of an unfiltered
* picker is noise, and the seven interactive sessions you actually want are buried.
*
* FAILS OPEN. An unknown entrypoint (23 of 2,018, where the marker fell outside the
* head we read) counts as a human session, because hiding a real conversation is a much
* worse error than showing a spurious one.
*/
export function isAgentSession(row: SessionRow): boolean {
return row.entrypoint !== undefined && row.entrypoint !== "cli";
}
/** One worktree (or the repo root) and every session recorded inside it. */
export interface WorktreeGroup {
/** Worktree name, or `(root)` for the main checkout. */
name: string;
/** Absolute path when known from git; null for a worktree that has been deleted. */
path: string | null;
/** Whether git still lists this worktree. Sessions outlive their worktree. */
live: boolean;
/** Whether this is the worktree claudish is running in. */
current: boolean;
sessions: SessionRow[];
/** mtime of the most recent session in the group. */
lastActiveMs: number;
/** Branch checked out in this worktree, short form. Absent for a deleted one. */
branch?: string;
/**
* When the worktree came into existence.
*
* The directory's birthtime for a live worktree — the honest answer, and free from the
* `stat` we already do. For a deleted one there is no directory left, so it falls back
* to the OLDEST session recorded in it, which is when work there demonstrably started.
*/
createdMs?: number;
/** Whether any session here is still being written. */
activeNow: boolean;
/** Changed files (`git status --porcelain`). Undefined until enrichment resolves. */
dirty?: number;
/** Commits ahead of / behind upstream. Undefined when there is no upstream. */
ahead?: number;
behind?: number;
}
export interface RepoContext {
/** The main checkout's absolute path. */
root: string;
/** The worktree cwd currently sits in (may equal `root`). */
current: string;
/** Absolute paths of every worktree git still knows about, including `root`. */
liveWorktrees: string[];
/** Worktree path → short branch name. Parsed from the same porcelain block, so free. */
branchByPath: Map<string, string>;
}
/**
* Locate the repository and its live worktrees.
*
* `--git-common-dir` is what distinguishes the main checkout from a worktree: inside a
* worktree `--show-toplevel` is the worktree itself, while the common dir still points
* at the parent's `.git`. Returns null outside a repository, which is a normal
* condition (the picker then falls back to every project directory).
*/
export function getRepoContext(cwd: string = process.cwd()): RepoContext | null {
const git = (args: string[]): string | null => {
try {
return execFileSync("git", args, {
cwd,
encoding: "utf-8",
stdio: ["ignore", "pipe", "ignore"],
}).trim();
} catch {
return null;
}
};
const current = git(["rev-parse", "--show-toplevel"]);
const commonDir = git(["rev-parse", "--git-common-dir"]);
if (!current || !commonDir) return null;
// `--git-common-dir` answers an absolute `/repo/.git` from a worktree and a bare
// `.git` from the main checkout, so only the absolute form identifies the root.
const root = commonDir.endsWith("/.git") ? commonDir.slice(0, -"/.git".length) : current;
// `git worktree list --porcelain` emits a block per worktree:
// worktree /abs/path
// HEAD <sha>
// branch refs/heads/<name> (absent when detached)
// so the branch comes out of the call we already make, at no extra cost.
const liveWorktrees: string[] = [];
const branchByPath = new Map<string, string>();
const porcelain = git(["worktree", "list", "--porcelain"]);
if (porcelain) {
let currentPath: string | null = null;
for (const line of porcelain.split("\n")) {
if (line.startsWith("worktree ")) {
currentPath = line.slice("worktree ".length);
liveWorktrees.push(currentPath);
} else if (line.startsWith("branch ") && currentPath) {
branchByPath.set(currentPath, line.slice("branch ".length).replace(/^refs\/heads\//, ""));
}
}
}
return { root, current, liveWorktrees, branchByPath };
}
/** `projectsDir()` entries, or `[]` when the directory does not exist yet. */
function projectDirs(): string[] {
try {
return readdirSync(projectsDir(), { withFileTypes: true })
.filter((e) => e.isDirectory())
.map((e) => e.name);
} catch {
return [];
}
}
/** Transcript files in one project directory, as `stat`-only rows. */
function sessionsIn(dirName: string): SessionRow[] {
const dir = join(projectsDir(), dirName);
let names: string[];
try {
names = readdirSync(dir).filter((n) => n.endsWith(".jsonl"));
} catch {
return [];
}
const rows: SessionRow[] = [];
for (const n of names) {
const file = join(dir, n);
try {
const st = statSync(file);
// A zero-byte transcript is a session that died before writing anything; it
// cannot be resumed into anything meaningful, so it is not offered.
if (st.size === 0) continue;
const row: SessionRow = {
id: basename(n, ".jsonl"),
file,
mtimeMs: st.mtimeMs,
birthtimeMs: st.birthtimeMs,
sizeBytes: st.size,
};
// Classify here, in the list pass, because `entrypoint` decides whether the row is
// shown at all — a lazily-hydrated filter would paint 2,000 rows and then collapse
// to 70. MEASURED at 8 KB: 97ms across 2,018 files and the marker is found in
// 1,995 of them; at 4 KB it misses 305, which is not worth the saving.
const head = readChunk(file, 0, Math.min(ENTRYPOINT_BYTES, st.size));
const m = /"entrypoint":"([a-z-]+)"/.exec(head);
if (m) row.entrypoint = m[1];
rows.push(row);
} catch {
// Raced with a delete. Skip.
}
}
return rows;
}
/**
* Fill in each live worktree's `dirty` / `ahead` / `behind`, off the render path.
*
* SPLIT FROM DISCOVERY ON PURPOSE, because the two have very different costs. MEASURED
* on this repo: `git for-each-ref` answers ahead/behind for EVERY branch in one 16ms
* call, while `git status --porcelain` costs ~40ms per worktree and cannot be batched —
* 331ms across eight worktrees. Discovery itself is 10–17ms, so folding status into it
* would make the picker twenty times slower to appear in exchange for a column most
* users glance at once.
*
* So the picker paints immediately with what is free (branch, dates, activity) and calls
* this afterwards; rows fill in as it resolves. Mutates the groups in place and resolves
* when every probe has settled. Never throws — a worktree whose status cannot be read
* simply keeps `undefined`, which the UI renders as "unknown" rather than as "clean".
*/
export async function enrichWorktreeGit(groups: WorktreeGroup[], repoRoot: string): Promise<void> {
const run = (cwd: string, args: string[]): Promise<string> =>
new Promise((resolve) => {
execFile("git", args, { cwd, encoding: "utf-8" }, (err, stdout) =>
resolve(err ? "" : stdout)
);
});
// One call for every branch's upstream tracking, e.g. `main [ahead 2, behind 1]`.
const trackByBranch = new Map<string, { ahead?: number; behind?: number }>();
const refs = await run(repoRoot, [
"for-each-ref",
"--format=%(refname:short)\t%(upstream:track)",
"refs/heads/",
]);
for (const line of refs.split("\n")) {
const [name, track] = line.split("\t");
if (!name || !track) continue;
const ahead = /ahead (\d+)/.exec(track)?.[1];
const behind = /behind (\d+)/.exec(track)?.[1];
if (ahead || behind) {
trackByBranch.set(name, {
...(ahead ? { ahead: Number(ahead) } : {}),
...(behind ? { behind: Number(behind) } : {}),
});
}
}
// Status is per-worktree and unbatchable, so run them concurrently rather than in
// series — the cost becomes the slowest single probe instead of their sum.
await Promise.all(
groups.map(async (g) => {
if (g.branch) Object.assign(g, trackByBranch.get(g.branch) ?? {});
if (!g.path || !g.live) return;
const out = await run(g.path, ["status", "--porcelain"]);
g.dirty = out.split("\n").filter((l) => l.trim().length > 0).length;
})
);
}
/** True when `p` is `root` itself or lives beneath it. Path-segment aware, so
* `/repo-old` is NOT under `/repo` — the exact confusion the slug cannot avoid. */
function isUnder(p: string, root: string): boolean {
return p === root || p.startsWith(`${root}/`);
}
/**
* The absolute `cwd` a project directory's sessions ran in, read from a transcript.
*
* Claude Code records `cwd` on most records, so the head of any one transcript settles
* what the lossy slug cannot: whether `-Users-j-mag-claudish-old` is this repo's
* `old/` subdirectory or a different checkout called `claudish-old`.
*
* Deliberately called ONLY for the ambiguous case — a directory whose slug extends the
* root's with no worktree marker. Doing it for all 219 project directories on this
* machine would put ~200 file opens on the picker's startup path to answer a question
* git has already answered for every case that matters.
*
* The known gap, stated rather than hidden: a DELETED worktree that lived outside the
* root is invisible — git no longer lists it and its slug does not extend the root's, so
* nothing points at it. Finding those would cost the full scan this avoids.
*/
function readProjectCwd(dirName: string): string | null {
const rows = sessionsIn(dirName);
if (rows.length === 0) return null;
// Newest first: an old transcript may predate a directory move.
rows.sort((a, b) => b.mtimeMs - a.mtimeMs);
for (const row of rows.slice(0, 2)) {
for (const r of parseRecords(
readChunk(row.file, 0, Math.min(HEAD_BYTES, row.sizeBytes)),
false
)) {
if (typeof r.cwd === "string" && r.cwd) return r.cwd;
}
}
return null;
}
/**
* A session is treated as LIVE when its transcript was touched within this window.
*
* Claude Code appends continuously while a session is open — mode lines, snapshots and
* titles land alongside messages — so a recent mtime is a good liveness proxy and the
* only one available without inspecting processes. 120s is deliberately generous: the
* cost of calling a finished session "active" is a misleading dot, while the cost of
* calling a live one dead is offering to resume a session that is currently writing,
* which is the genuinely damaging mistake.
*/
export const ACTIVE_WINDOW_MS = 120_000;
export function isActive(row: SessionRow, now = Date.now()): boolean {
return now - row.mtimeMs < ACTIVE_WINDOW_MS;
}
/**
* Group every session belonging to `repo` by worktree.
*
* Assignment is by LONGEST MATCHING SLUG PREFIX against the known worktree paths, which
* is what correctly folds a session started in a subdirectory back into its worktree:
* `…-worktrees-gemini-fix-packages-cli` is a session run from `packages/cli` inside the
* `gemini-fix` worktree, not a worktree called `gemini-fix-packages-cli`. Matching
* shortest-first would put it in its own phantom group, and splitting the slug on `-`
* cannot work at all because worktree names contain dashes.
*
* Worktrees git no longer lists still appear, marked `live: false`. Their transcripts
* remain on disk and remain resumable, and hiding them would silently drop history.
*/
export function discoverWorktreeGroups(repo: RepoContext): WorktreeGroup[] {
const rootSlug = slugForPath(repo.root);
// EVERY project directory is considered, not just those whose slug starts with the
// root's. A slug-prefix filter is wrong in both directions, because the slug is lossy:
// - it ADMITS a foreign sibling — `/Users/j/mag/claudish-old` slugs to
// `-Users-j-mag-claudish-old`, which prefix-matches the root just as a real
// subdirectory would, so another project's sessions get listed as resumable here;
// - it DROPS a legitimate worktree created outside the root, which
// `git worktree add ../repo-feature` does by default — git knows about it, the
// prefix test does not, and it never reaches the picker at all.
// Ownership is decided below against git's own worktree list and, where that cannot
// settle it, against the transcript's recorded `cwd`.
const mine = projectDirs();
// Longest first so the most specific worktree claims a directory before the root does.
const known = [...repo.liveWorktrees]
.map((p) => ({ path: p, slug: slugForPath(p) }))
.sort((a, b) => b.slug.length - a.slug.length);
const groups = new Map<string, WorktreeGroup>();
/**
* Group name → the absolute `cwd` its sessions recorded, for the dead-worktree fold
* below. Populated lazily and only for groups with no live path, since that is the
* only case the fold has to adjudicate.
*/
const groupCwd = new Map<string, string>();
const upsert = (name: string, path: string | null, live: boolean): WorktreeGroup => {
let g = groups.get(name);
if (!g) {
g = {
name,
path,
live,
current: path !== null && path === repo.current,
sessions: [],
lastActiveMs: 0,
activeNow: false,
...(path ? { branch: repo.branchByPath.get(path) } : {}),
};
groups.set(name, g);
}
return g;
};
const WORKTREE_MARK = "--claude-worktrees-";
// The root's slug is a prefix of EVERY worktree directory under it
// (`-Users-jack-mag-claudish` prefixes `-Users-jack-mag-claudish--claude-worktrees-x`),
// so the root must never win a prefix match — it would swallow every worktree whose
// directory no live worktree claims. MEASURED before this exclusion: 43 project
// directories collapsed into 6 groups, with 1,471 sessions wrongly filed under
// `(root)`. Worktree ownership is therefore decided by the MARKER first, and the
// root only claims directories that have no marker at all.
const worktreeMatches = known.filter((k) => k.path !== repo.root);
for (const dir of mine) {
const at = dir.indexOf(WORKTREE_MARK);
let name: string;
let path: string | null;
let live: boolean;
// 1. A worktree git currently lists, matched on its REAL path's slug. This is the
// only branch that can see a worktree living outside the root.
const hit = worktreeMatches.find((k) => dir === k.slug || dir.startsWith(`${k.slug}-`));
if (hit) {
path = hit.path;
live = true;
name = hit.path === repo.root ? "(root)" : basename(hit.path);
} else if (at !== -1 && dir.startsWith(rootSlug)) {
// 2. A worktree git no longer lists, nested under this root. Its transcripts
// survive and stay resumable, so it keeps a group. Un-slugging is lossy, so a
// deleted worktree's subdirectory sessions may carry a suffix in the heading
// rather than being silently merged or dropped.
path = null;
live = false;
name = dir.slice(at + WORKTREE_MARK.length);
} else if (dir === rootSlug) {
// 3. The main checkout itself.
name = "(root)";
path = repo.root;
live = true;
} else if (dir.startsWith(`${rootSlug}-`) && at === -1) {
// 4. AMBIGUOUS: the slug extends the root's, with no worktree marker. That is
// either a subdirectory of this repo (`<root>/packages/cli`) or a different
// project whose name merely starts the same way (`<root>-old`, `<root>.bak` —
// `.` slugs to `-` too). The slug cannot tell them apart, so ask the
// transcript, which records the absolute `cwd` it ran in.
const cwd = readProjectCwd(dir);
if (!cwd || !isUnder(cwd, repo.root)) continue; // a foreign sibling — not ours
name = "(root)";
path = repo.root;
live = true;
} else {
// Belongs to some other repository entirely.
continue;
}
const g = upsert(name, path, live);
if (path) groupCwd.set(name, path);
else if (!groupCwd.has(name)) {
const cwd = readProjectCwd(dir);
if (cwd) groupCwd.set(name, cwd);
}
for (const s of sessionsIn(dir)) {
g.sessions.push(s);
if (s.mtimeMs > g.lastActiveMs) g.lastActiveMs = s.mtimeMs;
}
}
// Fold a deleted worktree's subdirectory groups back into the worktree itself.
//
// A live worktree gets this free from the prefix match against its real path, but a
// deleted one has no path to match, so `mcp-failed-auth` and
// `mcp-failed-auth-packages-cli` arrive as two headings for one worktree. Names are
// all we have, so the fold is name-based: a group merges into the LONGEST other group
// whose name it extends with a `-`. That rule cannot merge two genuinely different
// worktrees, because a worktree named `foo-bar` only absorbs `foo-bar-<something>`,
// and if a real worktree `foo-bar-baz` also exists it is itself a group and wins by
// being longer.
const names = [...groups.keys()].sort((a, b) => b.length - a.length);
for (const name of [...groups.keys()]) {
const g = groups.get(name);
if (!g || g.live) continue;
const parent = names.find((n) => n !== name && name.startsWith(`${n}-`) && groups.has(n));
if (!parent) continue;
const into = groups.get(parent)!;
// NAME SHAPE IS NOT ENOUGH — confirm the descent against the recorded `cwd`.
//
// The name test cannot tell "a subdirectory of worktree X" from "a sibling worktree
// called X-something". For LIVE worktrees git settles it, but two DEAD siblings both
// reach here: worktrees `resume` and `resume-message` under one root would see
// `resume-message` folded into `resume`, losing its heading and filing its sessions
// under an unrelated worktree — the "silently drop history" outcome this pass exists
// to avoid. So the transcripts decide: fold only when the child really did run
// beneath the parent.
const childCwd = groupCwd.get(name);
const parentCwd = groupCwd.get(parent);
if (!childCwd || !parentCwd || !isUnder(childCwd, parentCwd)) continue;
into.sessions.push(...g.sessions);
into.lastActiveMs = Math.max(into.lastActiveMs, g.lastActiveMs);
groups.delete(name);
}
for (const g of groups.values()) {
g.sessions.sort((a, b) => b.mtimeMs - a.mtimeMs);
g.activeNow = g.sessions.some((s) => isActive(s));
// Birthtime for a live worktree is the real creation moment. For a deleted one the
// directory is gone, so the oldest session is the best available evidence of when
// work there began.
if (g.path) {
try {
g.createdMs = statSync(g.path).birthtimeMs;
} catch {
/* removed under us; fall through to the session-based estimate */
}
}
if (!g.createdMs && g.sessions.length > 0) {
g.createdMs = g.sessions.reduce((m, s) => Math.min(m, s.mtimeMs), Number.POSITIVE_INFINITY);
}
}
// Current worktree first, then most recently active. The current worktree is almost
// always what the user means, and making them hunt for it would defeat the point.
return [...groups.values()]
.filter((g) => g.sessions.length > 0)
.sort((a, b) => {
if (a.current !== b.current) return a.current ? -1 : 1;
return b.lastActiveMs - a.lastActiveMs;
});
}
// ---------------------------------------------------------------------------
// Lazy hydration — bounded reads only
// ---------------------------------------------------------------------------
const HEAD_BYTES = 64 * 1024;
const TAIL_BYTES = 128 * 1024;
/** Read up to `len` bytes at `pos`. Returns "" on any I/O failure. */
function readChunk(file: string, pos: number, len: number): string {
if (len <= 0) return "";
let fd: number | null = null;
try {
fd = openSync(file, "r");
const buf = Buffer.allocUnsafe(len);
const n = readSync(fd, buf, 0, len, pos);
return buf.subarray(0, n).toString("utf-8");
} catch {
return "";
} finally {
if (fd !== null) {
try {
closeSync(fd);
} catch {
/* already gone */
}
}
}
}
/** Parse the complete JSONL records in a chunk, discarding partial edge lines. */
function parseRecords(chunk: string, dropFirstPartial: boolean): Record<string, unknown>[] {
const lines = chunk.split("\n");
// A tail chunk almost always begins mid-record, and a head chunk almost always ends
// mid-record. Dropping the affected edge is why a bounded read is safe at all.
if (dropFirstPartial) lines.shift();
else lines.pop();
const out: Record<string, unknown>[] = [];
for (const l of lines) {
if (!l) continue;
try {
const o = JSON.parse(l);
if (o && typeof o === "object") out.push(o);
} catch {
/* truncated or not a record */
}
}
return out;
}
/**
* Flatten Claude Code's string-or-blocks message content to plain text.
*
* Blocks join with a NEWLINE, not a space. They are separate paragraphs of one message,
* and the reader renders them as such; every other consumer runs the result through
* `cleanPrompt`, which collapses all whitespace, so the separator is invisible to them
* and the length `lastMessageChars` reports is unchanged either way.
*/
function contentText(content: unknown): string {
if (typeof content === "string") return content;
if (!Array.isArray(content)) return "";
return content
.map((b) =>
b && typeof b === "object" && typeof (b as any).text === "string" ? (b as any).text : ""
)
.join("\n");
}
/**
* Strip the envelopes Claude Code wraps around slash commands and hook output, so a
* session invoked as `/investigate` previews as its actual prompt rather than as
* `<command-message>investigate</command-message><command-name>…`.
*/
/**
* Envelopes the HARNESS posts as `user` records, which no human typed.
*
* A Claude Code transcript records more than a conversation on the `user` side. Tool
* results are the obvious case and are already filtered by shape, but background-task
* events arrive as ordinary `user` records carrying a `<task-notification>` payload — and
* `cleanPrompt` strips the tags and keeps the body, so one surfaced in the transcript tail
* as `you b8kmietd6 Monitor event: "v7.45.0 release run and npm publish"`. Attributing a
* callback to the person is worse than dropping a turn: the panel exists to show what was
* last ASKED, and the reader has no way to tell the misattribution from the real thing.
*
* Matched on the RAW text before `cleanPrompt`, because cleaning is what destroys the
* evidence. `[Request interrupted by user]` is a harness marker too — a real action, but
* not prose, and it says nothing about where the session got to.
*/
const HARNESS_ENVELOPES = [
"<task-notification>",
"<system-reminder>",
"<local-command-stdout>",
"<user-prompt-submit-hook>",
] as const;
export function isHarnessNoise(raw: string): boolean {
const t = raw.trimStart();
if (t.startsWith("[Request interrupted by user")) return true;
return HARNESS_ENVELOPES.some((e) => t.startsWith(e));
}
/**
* One turn of the MAIN conversation, before any presentation-level cleaning.
*
* `raw` is exactly what the record carried, joined across its text blocks — no envelope
* stripping, no whitespace collapsing. The two consumers want different cleanings (the
* picker's preview collapses a turn to one line; the reader keeps its paragraphs), and a
* shared helper that had already collapsed the text could not serve the second.
*/
export interface RawTurn {
role: "user" | "assistant";
raw: string;
}
/**
* THE definition of "a turn of the main conversation", in one place.
*
* Every surface that reads a transcript needs the same five exclusions, and they are not
* guessable from the record shape alone — which is why they live here rather than being
* re-derived at each call site:
*
* 1. only `user` and `assistant` records are conversation at all (a transcript also
* carries `ai-title`, `mode`, `attachment`, `file-history-snapshot`, …);
* 2. `isMeta` marks a record the harness posted, not prose;
* 3. `isSidechain` marks SUBAGENT traffic — a different conversation that happens to
* share the file;
* 4. a `user` record whose content is a `tool_result` is the harness replying to the
* model, not the person speaking;
* 5. `isHarnessNoise` catches the envelopes (`<task-notification>`, `<system-reminder>`,
* hook output, interrupt markers) that arrive as ordinary `user` records.
*
* Returns `null` for anything that fails one of them, or that carries no text at all —
* an assistant record holding only `tool_use` or `thinking` blocks has no prose in it.
*/
export function mainConversationTurn(r: Record<string, unknown>): RawTurn | null {
if (r.type !== "user" && r.type !== "assistant") return null;
if (r.isMeta || r.isSidechain) return null;
const content = (r.message as { content?: unknown } | undefined)?.content;
if (
Array.isArray(content) &&
content.some((b) => (b as { type?: unknown })?.type === "tool_result")
) {
return null;
}
const raw = contentText(content);
if (!raw.trim() || isHarnessNoise(raw)) return null;
return { role: r.type === "user" ? "user" : "assistant", raw };
}
function cleanPrompt(text: string): string {
return text
.replace(/<command-[a-z-]+>[\s\S]*?<\/command-[a-z-]+>/g, " ")
.replace(/<local-command-[a-z-]+>[\s\S]*?<\/local-command-[a-z-]+>/g, " ")
.replace(/<[^>]{1,40}>/g, " ")
.replace(/\s+/g, " ")
.trim();
}
/**
* Fill in a row's title, opening prompt, branch and last-message size.
*
* Idempotent and cheap to call from a render path: it returns immediately once
* `hydrated` is set, and touches at most 192 KB regardless of transcript size.
*/
export function hydrateSession(row: SessionRow): SessionRow {
if (row.hydrated) return row;
row.hydrated = true;
// Re-stat a LIVE session before reading its tail. `sizeBytes` was captured during the
// list pass, and a session that is still appending — exactly the ones the picker marks
// with a green dot, and the most likely thing a user picks — will have grown since.
// Using the stale size aims the tail window at the middle of the file, so the "current"
// title and last message come from an older part of it, or from nothing at all if it
// grew by more than TAIL_BYTES.
if (isActive(row)) {
try {
row.sizeBytes = statSync(row.file).size;
} catch {
// Deleted mid-scan; the bounded reads below cope with a stale size.
}
}
const head = parseRecords(readChunk(row.file, 0, Math.min(HEAD_BYTES, row.sizeBytes)), false);
for (const r of head) {
if (!row.gitBranch && typeof r.gitBranch === "string") row.gitBranch = r.gitBranch;
if (!row.firstPrompt && r.type === "user" && !r.isMeta) {
const raw = contentText((r.message as any)?.content);
const t = isHarnessNoise(raw) ? "" : cleanPrompt(raw);
if (t) row.firstPrompt = t;
}
if (row.gitBranch && row.firstPrompt) break;
}
// The title is regenerated as a session evolves, so the LAST `ai-title` is the current
// one — hence reading the tail rather than the head for it.
const tailStart = Math.max(0, row.sizeBytes - TAIL_BYTES);
const tail = parseRecords(
readChunk(row.file, tailStart, row.sizeBytes - tailStart),
tailStart > 0
);
for (let i = tail.length - 1; i >= 0; i--) {
const r = tail[i]!;
if (!row.title && r.type === "ai-title" && typeof r.aiTitle === "string" && r.aiTitle.trim()) {
row.title = r.aiTitle.trim();
}
if (row.lastMessageChars === undefined && r.type === "user" && !r.isMeta) {
const raw = contentText((r.message as any)?.content);
const t = isHarnessNoise(raw) ? "" : cleanPrompt(raw);
if (t) row.lastMessageChars = t.length;
}
}
row.recentTurns = extractRecentTurns(tail);
return row;
}
/**
* How far back the deep pass will look for a human turn, and why it exists at all.
*
* MEASURED on a 7.8 MB transcript in this repository: the last 128 KB (`TAIL_BYTES`, what
* `hydrateSession` reads) holds 25 assistant turns and ZERO human ones — the most recent
* thing the person said is roughly half a megabyte back, behind a wall of tool traffic.
* So the per-role quota below is necessary but not sufficient: it reserves the slot, and
* the slot stays empty because the record is outside the window.
*
* Widening `TAIL_BYTES` is the wrong fix. It is paid by EVERY row on EVERY keystroke —
* the list hydrates about twenty rows at a time — to serve a panel that shows one. This
* budget is paid once, for the selected row only, and only when the cheap window came up
* empty.
*/
const DEEP_TAIL_BYTES = 4 * 1024 * 1024;
/**
* A PER-ROLE quota, not a flat count, and the difference is the whole feature.
*
* "Last 6 turns" sounds like a conversation and is not one in an agentic transcript: the
* assistant narrates several prose turns per human prompt, so the trailing six are very
* often six assistant turns and the panel showed a monologue. The human's last message is
* usually present and merely further back — it is what says what the session was ASKED
* to do, which is most of what decides whether it is the one to resume. Reserving it a
* slot guarantees it appears however deep it sits.
*/
const RECENT_AI_TURNS = 5;
const RECENT_USER_TURNS = 1;
/**
* The last few real turns of a conversation, oldest → newest: the most recent human
* message plus the last handful from the model.
*
* Walks the tail BACKWARDS and stops as soon as both quotas are filled, so a 73 MB
* transcript costs the same as a small one — the records are already parsed by the caller
* either way. Reversing at the end restores chronological order, and because the walk is
* strictly backwards that is a true ordering, not a re-sort: the user turn lands wherever
* it actually occurred relative to the model's, above them when it came first.
*
* What counts as a turn is the rest of the difficulty. A Claude Code transcript is mostly
* NOT conversation: tool results are posted as `user` records, tool calls and thinking are
* blocks inside `assistant` records, and slash commands arrive wrapped in
* `<command-name>` envelopes. Rendering those verbatim would fill the panel with
* `[{"type":"tool_result"…}]` and teach the reader nothing. So a turn must carry actual
* prose: tool-result records are skipped outright, non-text blocks are dropped, and what
* survives is collapsed to one line.
*/
function extractRecentTurns(
records: Record<string, unknown>[]
): Array<{ role: "user" | "assistant"; text: string }> {
const out: Array<{ role: "user" | "assistant"; text: string }> = [];
let ai = 0;
let user = 0;
for (let i = records.length - 1; i >= 0; i--) {
if (ai >= RECENT_AI_TURNS && user >= RECENT_USER_TURNS) break;
const r = records[i]!;
if (r.type !== "user" && r.type !== "assistant") continue;
const role = r.type === "user" ? "user" : "assistant";
// Quota check BEFORE the content work: once a role is satisfied the remaining
// records of that role cost nothing but the type test.
if (role === "assistant" ? ai >= RECENT_AI_TURNS : user >= RECENT_USER_TURNS) continue;
const turn = mainConversationTurn(r);
if (!turn) continue;
const text = cleanPrompt(turn.raw);
if (!text) continue;
out.push({ role, text });
if (role === "assistant") ai++;
else user++;
}
return out.reverse();
}
/**
* Second pass for the DETAILS panel: go and find the human turn the cheap window missed.
*
* Runs at most once per row (`conversationDeepened`) and returns immediately when the
* turns already include a `user` — so on a short session, or any session where the person
* spoke recently, it costs one array scan and no I/O at all.
*
* IT DOES NOT RE-PARSE THE WINDOW. Handing 4 MB of JSONL to `parseRecords` would mean
* `JSON.parse` on every assistant record and every tool result in it, to keep one line.
* Instead the lines are filtered by SUBSTRING first — a `user` record always carries
* `"type":"user"` — and only the survivors are parsed, walking backwards so the first hit
* is the newest and the loop stops there.
*
* The turn is PREPENDED. It is necessarily older than everything `hydrateSession` found,
* because that pass looked at the newest bytes and found no human turn in them, so
* chronological order puts it first. What separates it from the model turns below it is
* tool traffic, not silence — the panel shows the last thing asked and the last things
* said, which is what it is for, not a contiguous slice of the transcript.
*/
export function hydrateConversation(row: SessionRow): SessionRow {
if (row.conversationDeepened) return row;
row.conversationDeepened = true;
const turns = row.recentTurns;
if (!turns || turns.some((t) => t.role === "user")) return row;
const start = Math.max(0, row.sizeBytes - DEEP_TAIL_BYTES);
const chunk = readChunk(row.file, start, row.sizeBytes - start);
if (!chunk) return row;
const lines = chunk.split("\n");
// A window that starts mid-file starts mid-line; that fragment is not a record.
if (start > 0) lines.shift();
for (let i = lines.length - 1; i >= 0; i--) {
const line = lines[i]!;
if (!line.includes('"type":"user"')) continue;
let r: Record<string, unknown>;
try {
r = JSON.parse(line) as Record<string, unknown>;
} catch {
continue;
}
const turn = mainConversationTurn(r);
if (!turn || turn.role !== "user") continue;
const text = cleanPrompt(turn.raw);
if (!text) continue;
turns.unshift({ role: "user", text });
if (row.lastMessageChars === undefined) row.lastMessageChars = text.length;
return row;
}
return row;
}
/** The best label available for a row: its title, else its opening prompt, else its id. */
export function sessionLabel(row: SessionRow): string {
return row.title || row.firstPrompt || row.id;
}
/**
* The newest transcript for `cwd` — the session that just ended.
*
* This is how the end-of-session summary learns the id to print in its resume command
* without claudish having to parse the child's stdout. Newest-by-mtime is exact here
* because the summary runs moments after the child exited, so the session it just ran
* is necessarily the most recently written transcript for that directory.
*/
export function findLatestSessionId(cwd: string = process.cwd(), sinceMs = 0): string | null {
// `sinceMs` bounds the guess to transcripts touched during THIS session.
//
// Newest-by-mtime is only "necessarily" the session that just ran when one session
// owns the directory. A second terminal in the same cwd, a `team` run or an MCP
// session child all write here too and any of them can be the most recently touched
// at the moment claudish exits — which would print a resume command naming someone
// else's conversation, as a line the user is invited to paste. Filtering by the
// proxy's start time cannot make the guess right, but it does make it fail closed:
// when nothing in this directory was written during the session, the answer is null
// and the card prints no resume line at all.
const touched = sessionsIn(slugForPath(cwd)).filter((r) => r.mtimeMs >= sinceMs);
if (touched.length === 0) return null;
// Prefer a transcript that was CREATED during this run, before falling back to the
// newest one merely touched during it.
//
// Newest-by-mtime alone loses to any conversation that is still being written in the
// same directory, and the loudest such writer is a Claude Code session that launched
// claudish in the first place: it appends on every turn, so it is always the freshest
// file at the moment claudish exits. MEASURED — a run inside this worktree printed
// `--resume 35188908-…`, the id of the OUTER session, while the child printed
// `49ca22f8-…` for itself. The child's transcript is the one born during the window;
// the outer session's predates it. A resumed session keeps its original file and so
// would be missed here, but that path never reaches this function: `resumedSessionId`
// is already known and takes precedence at the call site.
const born = touched.filter((r) => r.birthtimeMs !== undefined && r.birthtimeMs >= sinceMs);
const pool = born.length > 0 ? born : touched;
return pool.reduce((a, b) => (b.mtimeMs > a.mtimeMs ? b : a)).id;
}