@claude-transcripts/cli 0.0.14 → 0.0.16

package/README.md

@@ -90,6 +90,7 @@ upgrades in place: it's idempotent and keeps your history.
 |---|---|
 | `sessions [id] [options]` | List / inspect sessions (via the webapi) |
 | `search <query> [options]` | Search the corpus |
+| `turns [session] [options]` | Speaker-split turns: one session, or one speaker across all sessions |
 | `backfill [options]` | Adopt on-disk ~/.claude transcripts as first-class history |
 
 **Portability**
@@ -107,6 +108,7 @@ upgrades in place: it's idempotent and keeps your history.
 | `reindex` | Rebuild the search indexes from CouchDB |
 | `doctor [options]` | Smoke-test the write/read/search path end-to-end |
 | `hook [action] [options]` | The Claude Code hook, and its registration |
+| `statusline [action] [options]` | The Claude Code statusline indicator (recording / off), and its registration |
 
 **Global options** (every command)
 

package/dist/cli.js

@@ -29659,6 +29659,16 @@ var ACTIONS = [
     summary: "Reset counters + seed the chunk offset at start",
     implemented: false
   },
+  {
+    key: "announce-recording",
+    summary: "Tell the user, in the transcript, whether and where this session is recorded",
+    implemented: false
+  },
+  {
+    key: "inject-recall-policy",
+    summary: "Prime the session with the recall policy + how much history this cwd has",
+    implemented: false
+  },
   { key: "enrich-metadata", summary: "Post additional session metadata", implemented: false },
   {
     key: "extract-feature",
@@ -29679,7 +29689,15 @@ var ACTIONS = [
   }
 ];
 var BINDINGS = [
-  { event: "SessionStart", actions: ["seed-session-start", "write-event-marker"] },
+  {
+    event: "SessionStart",
+    actions: [
+      "seed-session-start",
+      "write-event-marker",
+      "announce-recording",
+      "inject-recall-policy"
+    ]
+  },
   {
     event: "UserPromptSubmit",
     actions: ["write-event-marker", "update-counts", "flush-transcript-chunk"]
@@ -29706,6 +29724,10 @@ var WEBAPI = {
   type: "string",
   description: "webapi base URL (default: $CT_WEBAPI_URL)"
 };
+var JSON_OUT = {
+  name: "--json",
+  description: "print the webapi response as JSON instead of a table"
+};
 var CLI_SPEC = {
   groups: [
     { key: "lifecycle", title: "Lifecycle" },
@@ -29732,6 +29754,7 @@ var CLI_SPEC = {
         },
         { name: "--meili-key", description: "generate a Meilisearch master key" },
         { name: "--no-hook", description: "skip Claude Code registration" },
+        { name: "--no-statusline", description: "register the hook but not the statusline" },
         { name: "--no-app", description: "skip the app container (run the webapi yourself)" },
         { name: "--no-prune", description: "keep superseded app images" },
         { name: "--skip-preflight", description: "continue past failed preflight checks" },
@@ -29792,9 +29815,10 @@ var CLI_SPEC = {
           name: "--limit",
           type: "number",
           description: "rows to list (default 50) / transcript entries to preview (default 30)"
-        }
+        },
+        JSON_OUT
       ],
-      examples: ["sessions", "sessions --limit 10", "sessions 3f9a2c1e --limit 80"]
+      examples: ["sessions", "sessions --limit 10", "sessions 3f9a2c1e --limit 80 --json"]
     },
     {
       name: "search",
@@ -29815,9 +29839,42 @@ var CLI_SPEC = {
           name: "--source",
           type: "string",
           description: "only this provenance (live | backfill | \u2026)"
-        }
+        },
+        JSON_OUT
       ],
-      examples: ['search "retry policy"', "search deploy --cwd ~/proj --limit 5"]
+      examples: ['search "retry policy"', "search deploy --cwd ~/proj --limit 5 --json"]
+    },
+    {
+      name: "turns",
+      group: "daily",
+      summary: "Speaker-split turns: one session, or one speaker across all sessions",
+      args: [
+        { name: "session", description: "session id \u2014 that session's turns (omit: all sessions)" },
+        {
+          name: "--role",
+          type: "string",
+          choices: ["user", "assistant", "tool_result", "system", "other"],
+          description: "only this speaker"
+        },
+        {
+          name: "--from",
+          type: "string",
+          description: "all sessions: only turns at/after this ISO instant"
+        },
+        {
+          name: "--to",
+          type: "string",
+          description: "all sessions: only turns at/before this ISO instant"
+        },
+        { name: "--limit", type: "number", default: 50, description: "turns to show" },
+        { name: "--skip", type: "number", description: "skip this many (paging)" },
+        JSON_OUT
+      ],
+      examples: [
+        "turns --role user --limit 200",
+        "turns --role user --from 2026-08-01 --json",
+        "turns 3f9a2c1e --role assistant"
+      ]
     },
     {
       name: "backfill",
@@ -29924,6 +29981,21 @@ var CLI_SPEC = {
         { name: "--dry-run", description: "with `install`: show the change without writing" }
       ],
       examples: ["hook status", "hook install --dry-run"]
+    },
+    {
+      name: "statusline",
+      group: "admin",
+      summary: "The Claude Code statusline indicator (recording / off), and its registration",
+      args: [
+        {
+          name: "action",
+          choices: ["render", "install", "uninstall", "status"],
+          default: "status",
+          description: "`render` reads Claude Code's statusline JSON from stdin and prints one line (no network)"
+        },
+        { name: "--dry-run", description: "with `install`: show the change without writing" }
+      ],
+      examples: ["statusline install", "statusline status"]
     }
   ]
 };
@@ -30248,6 +30320,97 @@ var HOOK_TYPES = [
   }
 ];
 
+// packages/shared/src/model/recall.ts
+var RECALL_MODES = ["off", "suggest", "auto"];
+var RECALL_SCOPES = ["project", "host", "all"];
+var DEFAULT_RECALL = {
+  mode: "auto",
+  scope: "project",
+  maxResults: 5,
+  maxSnippetChars: 400,
+  triggers: { priorWorkQuestion: true, repeatedError: true, beforeRederiving: true },
+  excludeCwdGlobs: [],
+  primer: { onSessionStart: true, maxTokens: 200 }
+};
+var RECALL_ENV = {
+  mode: "CLAUDE_PLUGIN_OPTION_RECALL_MODE",
+  scope: "CLAUDE_PLUGIN_OPTION_RECALL_SCOPE",
+  maxResults: "CLAUDE_PLUGIN_OPTION_MAX_RESULTS"
+};
+function resolveRecall(fromConfig, env = {}) {
+  const c = fromConfig ?? {};
+  const merged = {
+    ...DEFAULT_RECALL,
+    ...stripUndefined(c),
+    triggers: { ...DEFAULT_RECALL.triggers, ...stripUndefined(c.triggers ?? {}) },
+    primer: { ...DEFAULT_RECALL.primer, ...stripUndefined(c.primer ?? {}) },
+    excludeCwdGlobs: c.excludeCwdGlobs ?? DEFAULT_RECALL.excludeCwdGlobs
+  };
+  const mode = env[RECALL_ENV.mode];
+  if (mode && RECALL_MODES.includes(mode))
+    merged.mode = mode;
+  const scope = env[RECALL_ENV.scope];
+  if (scope && RECALL_SCOPES.includes(scope))
+    merged.scope = scope;
+  const max = Number(env[RECALL_ENV.maxResults]);
+  if (Number.isInteger(max) && max > 0)
+    merged.maxResults = max;
+  return merged;
+}
+function stripUndefined(o) {
+  const out = {};
+  for (const [k, v] of Object.entries(o))
+    if (v !== undefined)
+      out[k] = v;
+  return out;
+}
+function scopeFlag(scope, cwd, hostname) {
+  switch (scope) {
+    case "project":
+      return `--cwd "${cwd}"`;
+    case "host":
+      return `--hostname "${hostname}"`;
+    default:
+      return "";
+  }
+}
+function daysAgo(iso, now) {
+  if (!iso)
+    return "";
+  const d = Math.floor((now - Date.parse(iso)) / 86400000);
+  if (!Number.isFinite(d))
+    return "";
+  return d <= 0 ? "today" : d === 1 ? "yesterday" : `${d} days ago`;
+}
+function recallPrimer(policy, facts, where, now = Date.now()) {
+  if (policy.mode === "off" || !policy.primer.onSessionStart)
+    return null;
+  if (facts.sessionCount <= 0)
+    return null;
+  const scopeWord = { project: "this project", host: "this host", all: "all projects" }[policy.scope];
+  const recent = daysAgo(facts.mostRecent, now);
+  const flag = scopeFlag(policy.scope, where.cwd, where.hostname);
+  const when = [];
+  if (policy.triggers.priorWorkQuestion)
+    when.push("a question about why existing code or a decision is the way it is");
+  if (policy.triggers.repeatedError)
+    when.push("an error that looks familiar");
+  if (policy.triggers.beforeRederiving)
+    when.push("re-deriving something that looks like prior work here");
+  const action = policy.mode === "auto" ? "search history first" : "offer to search history, and search if the user agrees";
+  return [
+    `Session history for ${scopeWord} is available via \`claude-transcripts search "<query>" ${flag} --json --limit ${policy.maxResults}\`.`,
+    `${facts.sessionCount} recorded session${facts.sessionCount === 1 ? "" : "s"} in scope${recent ? `, most recent ${recent}` : ""}.`,
+    when.length ? `Before answering ${joinOr(when)}, ${action}.` : "",
+    `Cite the session id and date. Snippets only, never a whole transcript; max ${policy.maxResults} results. See the \`recall\` skill.`
+  ].filter(Boolean).join(" ");
+}
+function joinOr(items) {
+  if (items.length <= 1)
+    return items[0] ?? "";
+  return `${items.slice(0, -1).join(", ")}, or ${items[items.length - 1]}`;
+}
+
 // packages/shared/src/model/routes.ts
 var ROUTES = [
   { path: "/", serves: "machine-readable app manifest (agent entrypoint)" },
@@ -30685,6 +30848,7 @@ function buildAppModel(config, env = {}) {
     features: config.features,
     servicesMenu: buildServicesMenu(services, config.servicesMenu),
     system: config.system,
+    recall: resolveRecall(config.recall, env),
     cliSpec: CLI_SPEC
   };
 }
@@ -39061,6 +39225,38 @@ var getSessionTranscript = async (id, params, options) => {
     method: "GET"
   });
 };
+var getGetSessionTurnsUrl = (id, params) => {
+  const normalizedParams = new URLSearchParams;
+  Object.entries(params || {}).forEach(([key, value]) => {
+    if (value !== undefined) {
+      normalizedParams.append(key, value === null ? "null" : value.toString());
+    }
+  });
+  const stringifiedParams = normalizedParams.toString();
+  return stringifiedParams.length > 0 ? `/api/sessions/${id}/turns?${stringifiedParams}` : `/api/sessions/${id}/turns`;
+};
+var getSessionTurns = async (id, params, options) => {
+  return customFetch(getGetSessionTurnsUrl(id, params), {
+    ...options,
+    method: "GET"
+  });
+};
+var getGetTurnsUrl = (params) => {
+  const normalizedParams = new URLSearchParams;
+  Object.entries(params || {}).forEach(([key, value]) => {
+    if (value !== undefined) {
+      normalizedParams.append(key, value === null ? "null" : value.toString());
+    }
+  });
+  const stringifiedParams = normalizedParams.toString();
+  return stringifiedParams.length > 0 ? `/api/turns?${stringifiedParams}` : `/api/turns`;
+};
+var getTurns = async (params, options) => {
+  return customFetch(getGetTurnsUrl(params), {
+    ...options,
+    method: "GET"
+  });
+};
 var getIngestSummaryUrl = () => {
   return `/api/ingest/summary`;
 };
@@ -39738,7 +39934,20 @@ api_bind_addr = "[::]:3903"
     "garageWebui": "http://127.0.0.1:7655/",
     "meilisearch": "http://127.0.0.1:7656/"
   },
-  "userSettings": {}
+  "userSettings": {},
+  "recall": {
+    "mode": "auto",
+    "scope": "project",
+    "maxResults": 5,
+    "maxSnippetChars": 400,
+    "triggers": {
+      "priorWorkQuestion": true,
+      "repeatedError": true,
+      "beforeRederiving": true
+    },
+    "excludeCwdGlobs": [],
+    "primer": { "onSessionStart": true, "maxTokens": 200 }
+  }
 }
 `
   }
@@ -39996,9 +40205,95 @@ async function runExport(argv) {
 import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync3 } from "fs";
 import { dirname } from "path";
 
+// packages/cli/src/hook/announce.ts
+function sessionLink(webapiUrl2, sessionId) {
+  return webapiUrl2 ? `${webapiUrl2.replace(/\/$/, "")}/app/sessions/${sessionId}` : null;
+}
+function recordingBanner(targets, sessionId) {
+  const where = [`couchdb://${targets.couchUrl.replace(/^https?:\/\//, "")}/${targets.sessionsDb}`];
+  if (targets.bucket)
+    where.push(`s3://${targets.bucket}`);
+  if (targets.mirrors.length)
+    where.push(`${targets.mirrors.length} mirror(s)`);
+  const link2 = sessionLink(targets.webapiUrl, sessionId);
+  return `Claude Transcripts \u2014 recording to ${where.join(" + ")}${link2 ? ` \xB7 ${link2}` : ""}`;
+}
+var NOT_RECORDING_BANNER = "Claude Transcripts \u2014 not recording (no instance configured). Run `claude-transcripts install`.";
+function sessionStartEnvelope(out) {
+  if (!out.systemMessage && !out.additionalContext)
+    return null;
+  return {
+    ...out.systemMessage ? { systemMessage: out.systemMessage } : {},
+    ...out.additionalContext ? {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: out.additionalContext
+      }
+    } : {}
+  };
+}
+function emitSessionStart(out) {
+  try {
+    const envelope = sessionStartEnvelope(out);
+    if (envelope)
+      process.stdout.write(`${JSON.stringify(envelope)}
+`);
+  } catch {}
+}
+
 // packages/cli/src/hook/handlers.ts
 import { readFileSync as readFileSync6 } from "fs";
 
+// packages/cli/src/hook/recall.ts
+var FACTS_TIMEOUT_MS = 2000;
+function isExcluded(cwd2, globs) {
+  for (const g of globs) {
+    try {
+      if (new Bun.Glob(g).match(cwd2))
+        return true;
+    } catch {}
+  }
+  return false;
+}
+async function corpusFacts(webapiUrl2, policy, cwd2, hostname4) {
+  const q = new URLSearchParams({ limit: "1" });
+  if (policy.scope === "project")
+    q.set("cwd", cwd2);
+  else if (policy.scope === "host")
+    q.set("hostname", hostname4);
+  try {
+    const res = await fetch(`${webapiUrl2}/api/sessions?${q}`, {
+      signal: AbortSignal.timeout(FACTS_TIMEOUT_MS)
+    });
+    if (!res.ok)
+      return null;
+    const body = await res.json();
+    return {
+      sessionCount: body.totalCount ?? 0,
+      mostRecent: body.sessions?.[0]?.timestamp
+    };
+  } catch {
+    return null;
+  }
+}
+async function buildPrimer(ctx) {
+  const policy = resolveRecall(ctx.config.recall, process.env);
+  if (policy.mode === "off" || !policy.primer.onSessionStart)
+    return null;
+  if (!ctx.cwd || isExcluded(ctx.cwd, policy.excludeCwdGlobs))
+    return null;
+  let webapi;
+  try {
+    webapi = resolveWebapiUrl();
+  } catch {
+    return null;
+  }
+  const facts = await corpusFacts(webapi, policy, ctx.cwd, ctx.hostname);
+  if (!facts)
+    return null;
+  return recallPrimer(policy, facts, { cwd: ctx.cwd, hostname: ctx.hostname });
+}
+
 // packages/cli/src/hook/runtime.ts
 import {
   closeSync,
@@ -40116,7 +40411,7 @@ function loadHookConfig(path) {
     return null;
   }
 }
-function makeDirectCouch(config) {
+function makeDirectCouch(config, onWrite) {
   const root = config.couch.url;
   const headers = { "Content-Type": "application/json" };
   if (config.couch.auth)
@@ -40124,29 +40419,35 @@ function makeDirectCouch(config) {
   return {
     async postDoc(db, doc) {
       try {
-        await fetch(`${root}/${db}`, {
+        const res = await fetch(`${root}/${db}`, {
           method: "POST",
           headers,
           body: JSON.stringify(doc),
           signal: AbortSignal.timeout(5000)
         });
-      } catch {}
+        onWrite?.(res.ok);
+      } catch {
+        onWrite?.(false);
+      }
     },
     async putDoc(db, id, doc, timeoutMs = 5000) {
       try {
-        await fetch(`${root}/${db}/${encodeURIComponent(id)}`, {
+        const res = await fetch(`${root}/${db}/${encodeURIComponent(id)}`, {
           method: "PUT",
           headers,
           body: JSON.stringify(doc),
           signal: AbortSignal.timeout(timeoutMs)
         });
-      } catch {}
+        onWrite?.(res.ok);
+      } catch {
+        onWrite?.(false);
+      }
     }
   };
 }
-function makeCouch(config) {
+function makeCouch(config, onWrite) {
   const mirrors = config.mirrors ?? [];
-  return fanOutCouch([makeDirectCouch(config), ...mirrors.map((m) => makeMirrorCouch(m))]);
+  return fanOutCouch([makeDirectCouch(config, onWrite), ...mirrors.map((m) => makeMirrorCouch(m))]);
 }
 function makeDirectBlob(config) {
   const cfg = config.blob;
@@ -40206,6 +40507,67 @@ function makeCounts(sessionId) {
     }
   };
 }
+function targetsFile(sessionId) {
+  return `/tmp/claude-transcripts-${sessionId}.targets`;
+}
+function makeTargets(sessionId) {
+  const file = targetsFile(sessionId);
+  const read = () => {
+    try {
+      return JSON.parse(readFileSync5(file, "utf8"));
+    } catch {
+      return null;
+    }
+  };
+  const write = (t) => {
+    try {
+      writeFileSync2(file, JSON.stringify(t));
+    } catch {}
+  };
+  return {
+    read,
+    write,
+    markWrite(ok) {
+      const t = read();
+      if (!t)
+        return;
+      if (ok) {
+        t.lastWriteMs = Date.now();
+        t.lastFailureMs = 0;
+      } else {
+        t.lastFailureMs = Date.now();
+      }
+      write(t);
+    },
+    clear() {
+      try {
+        unlinkSync(file);
+      } catch {}
+    }
+  };
+}
+function redactUrl(url) {
+  try {
+    const u = new URL(url);
+    u.username = "";
+    u.password = "";
+    return u.toString().replace(/\/$/, "");
+  } catch {
+    return url;
+  }
+}
+function resolveTargets(config, webapiUrl2) {
+  return {
+    couchUrl: redactUrl(config.couch.url),
+    sessionsDb: config.couch.databases.sessions ?? DEFAULT_SESSIONS_DB,
+    bucket: config.blob?.accessKey ? config.blob.buckets.sessions : undefined,
+    webapiUrl: webapiUrl2,
+    features: Object.entries(config.features ?? {}).filter(([, on]) => on).map(([k]) => k),
+    mirrors: (config.mirrors ?? []).map((m) => redactUrl(m.url)),
+    lastWriteMs: 0,
+    lastFailureMs: 0
+  };
+}
 var STALE_LOCK_MS = 30000;
 function makeChunkState(sessionId) {
   const stateFile = `/tmp/claude-transcripts-${sessionId}.chunkstate`;
@@ -40268,12 +40630,15 @@ function makeChunkState(sessionId) {
     }
   };
 }
+var DEFAULT_SESSIONS_DB = "claude-transcripts-sessions";
 function buildContext(payload, config) {
   const event = payload?.hook_event_name;
   const sessionId = payload?.session_id;
   if (!event || !sessionId)
     return null;
+  const targets = makeTargets(sessionId);
   return {
+    output: {},
     event,
     sessionId,
     cwd: payload?.cwd ?? "",
@@ -40282,10 +40647,11 @@ function buildContext(payload, config) {
     transcriptPath: payload?.transcript_path,
     payload,
     config,
-    couch: makeCouch(config),
+    couch: makeCouch(config, (ok) => targets.markWrite(ok)),
     blob: makeBlob(config),
     counts: makeCounts(sessionId),
-    sessionsDb: config.couch.databases.sessions ?? "claude-transcripts-sessions",
+    targets,
+    sessionsDb: config.couch.databases.sessions ?? DEFAULT_SESSIONS_DB,
     sessionsBucket: config.blob?.buckets.sessions
   };
 }
@@ -40306,6 +40672,23 @@ var seedSessionStart = async (ctx) => {
     ctx.counts.reset();
     makeChunkState(ctx.sessionId).seed();
   }
+  ctx.targets.write(resolveTargets(ctx.config, safeWebapiUrl()));
+};
+function safeWebapiUrl() {
+  try {
+    return resolveWebapiUrl();
+  } catch {
+    return;
+  }
+}
+var announceRecording = async (ctx) => {
+  const targets = ctx.targets.read() ?? resolveTargets(ctx.config, safeWebapiUrl());
+  ctx.output.systemMessage = recordingBanner(targets, ctx.sessionId);
+};
+var injectRecallPolicy = async (ctx) => {
+  const primer = await buildPrimer(ctx);
+  if (primer)
+    ctx.output.additionalContext = primer;
 };
 var updateCounts = async (ctx) => {
   ctx.counts.inc("events");
@@ -40454,6 +40837,7 @@ var writeSummary = async (ctx) => {
     await ctx.blob.put(ctx.sessionsBucket, `${ctx.sessionId}/summary.json`, JSON.stringify(doc), "application/json");
   }
   ctx.counts.clear();
+  ctx.targets.clear();
 };
 var uploadBlobs = async (ctx) => {
   if (!ctx.blob.enabled || !ctx.sessionsBucket || !ctx.transcriptPath)
@@ -40468,6 +40852,8 @@ var uploadBlobs = async (ctx) => {
 };
 var HANDLERS = {
   "seed-session-start": seedSessionStart,
+  "announce-recording": announceRecording,
+  "inject-recall-policy": injectRecallPolicy,
   "update-counts": updateCounts,
   "write-event-marker": writeEventMarker,
   "flush-transcript-chunk": flushTranscriptChunk,
@@ -40495,8 +40881,12 @@ async function dispatch(raw, configPath) {
     return { ran: false, actions: [] };
   }
   const config = loadHookConfig(configPath);
-  if (!config)
+  if (!config) {
+    if (payload?.hook_event_name === "SessionStart") {
+      emitSessionStart({ systemMessage: NOT_RECORDING_BANNER });
+    }
     return { ran: false, actions: [] };
+  }
   const ctx = buildContext(payload, config);
   if (!ctx)
     return { ran: false, actions: [] };
@@ -40511,6 +40901,8 @@ async function dispatch(raw, configPath) {
       console.error(`[hook] action ${key} failed (ignored):`, err);
     }
   }));
+  if (ctx.event === "SessionStart")
+    emitSessionStart(ctx.output);
   return { ran: true, event: ctx.event, actions: actions2 };
 }
 
@@ -40523,12 +40915,14 @@ function readSettings(path) {
   }
 }
 function hookCommand() {
+  return `${cliInvocation()} hook run`;
+}
+function cliInvocation() {
   const exec3 = process.execPath;
   const isCompiled = !/\/bun$/.test(exec3);
   if (isCompiled)
-    return `${exec3} hook run`;
-  const entry = Bun.main;
-  return `${exec3} run ${entry} hook run`;
+    return exec3;
+  return `${exec3} run ${Bun.main}`;
 }
 function isOurCommand(command) {
   if (!command?.includes("hook run"))
@@ -40911,7 +41305,7 @@ async function runImport(argv) {
 }
 
 // packages/cli/src/commands/install.ts
-import { existsSync as existsSync8, readFileSync as readFileSync11 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync12 } from "fs";
 
 // packages/cli/src/lib/assets.ts
 import {
@@ -41291,7 +41685,8 @@ function buildHookConfig(app, env4) {
       buckets: app.s3.buckets
     } : undefined,
     features: app.features,
-    system: app.system
+    system: app.system,
+    ...app.recall ? { recall: app.recall } : {}
   };
 }
 var PRESERVED_KEYS = ["mirrors"];
@@ -41514,6 +41909,163 @@ var hasFailures = (checks) => checks.some((c) => c.status === "fail");
 var DEV_VERSION = "0.0.0-dev";
 var VERSION = process.env.CT_VERSION ?? DEV_VERSION;
 
+// packages/cli/src/commands/statusline.ts
+import { existsSync as existsSync8, mkdirSync as mkdirSync7, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "fs";
+import { dirname as dirname5 } from "path";
+
+// packages/cli/src/lib/statusline.ts
+var STALL_AFTER_MS = 60000;
+function ago(ms, now2) {
+  const s = Math.max(0, Math.round((now2 - ms) / 1000));
+  if (s < 60)
+    return `${s}s ago`;
+  const m = Math.round(s / 60);
+  if (m < 60)
+    return `${m}m ago`;
+  return `${Math.round(m / 60)}h ago`;
+}
+function whereLabel(t) {
+  const host = t.couchUrl.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+  return `${t.sessionsDb}@${host}`;
+}
+function renderStatusline(state, now2 = Date.now()) {
+  if (!state.configured)
+    return "\u25CB ct off \xB7 no instance configured";
+  const t = state.targets;
+  if (!t)
+    return "\u25CB ct off \xB7 not recording this session";
+  const c = state.counts;
+  const toolCalls = c ? Object.values(c.tools).reduce((a, b) => a + b, 0) : 0;
+  const counts = c ? `${c.events} ev \xB7 ${toolCalls} tools` : "0 ev";
+  const written = t.lastWriteMs > 0;
+  const failing = t.lastFailureMs > t.lastWriteMs && now2 - t.lastWriteMs > STALL_AFTER_MS;
+  if (failing) {
+    const last2 = written ? `last write ${ago(t.lastWriteMs, now2)}` : "no write landed";
+    return `\u25D0 ct stalled \xB7 ${counts} \xB7 ${last2} \u2192 ${whereLabel(t)}`;
+  }
+  if (!written)
+    return `\u25CC ct ready \xB7 ${counts} \xB7 no write yet \u2192 ${whereLabel(t)}`;
+  return `\u25CF ct rec \xB7 ${counts} \xB7 ${ago(t.lastWriteMs, now2)} \u2192 ${whereLabel(t)}`;
+}
+
+// packages/cli/src/commands/statusline.ts
+function readSettings2(path) {
+  try {
+    return JSON.parse(readFileSync11(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function statuslineCommand() {
+  return `${cliInvocation()} statusline render`;
+}
+function isOurStatusline(s) {
+  const c = s?.command ?? "";
+  return c.includes("claude-transcripts-statusline") || c.includes("statusline render");
+}
+async function render2() {
+  try {
+    let input = {};
+    try {
+      input = JSON.parse(await Bun.stdin.text());
+    } catch {}
+    const configured = existsSync8(installPaths().hookConfig);
+    const id = input.session_id;
+    const line = renderStatusline({
+      configured,
+      targets: id ? makeTargets(id).read() : null,
+      counts: id ? makeCounts(id).read() : null
+    });
+    process.stdout.write(`${line}
+`);
+  } catch {
+    process.stdout.write(`\u25CB ct off
+`);
+  }
+  return 0;
+}
+function install2(argv) {
+  const { options } = parseFlags(argv);
+  const paths = installPaths();
+  const settings = readSettings2(paths.claudeSettings);
+  const command = statuslineCommand();
+  const next = { type: "command", command };
+  const existing = settings.statusLine;
+  if (existing && !isOurStatusline(existing)) {
+    console.log(`statusline: ${paths.claudeSettings} already has a statusLine that isn't ours:`);
+    console.log(`  ${JSON.stringify(existing)}`);
+    console.log("statusline: not overwriting it. To show the indicator alongside your own,");
+    console.log("statusline: have your command append the output of:");
+    console.log(`  ${command}`);
+    return 1;
+  }
+  if (existing?.command === command) {
+    console.log(`statusline: already registered \u2192 ${paths.claudeSettings}`);
+    return 0;
+  }
+  if (options["dry-run"] === true) {
+    console.log(`statusline: would set statusLine in ${paths.claudeSettings} to`);
+    console.log(`  ${JSON.stringify(next)}`);
+    return 0;
+  }
+  mkdirSync7(dirname5(paths.claudeSettings), { recursive: true });
+  writeFileSync7(paths.claudeSettings, `${JSON.stringify({ ...settings, statusLine: next }, null, 2)}
+`);
+  console.log(`statusline: registered \u2192 ${paths.claudeSettings}`);
+  console.log("statusline: restart any open Claude Code session for it to take effect.");
+  return 0;
+}
+function uninstall2() {
+  const paths = installPaths();
+  const settings = readSettings2(paths.claudeSettings);
+  if (!settings.statusLine) {
+    console.log("statusline: nothing registered.");
+    return 0;
+  }
+  if (!isOurStatusline(settings.statusLine)) {
+    console.log("statusline: the registered statusLine isn't ours; leaving it alone.");
+    return 1;
+  }
+  const { statusLine: _drop, ...rest2 } = settings;
+  writeFileSync7(paths.claudeSettings, `${JSON.stringify(rest2, null, 2)}
+`);
+  console.log(`statusline: removed from ${paths.claudeSettings}`);
+  return 0;
+}
+function status2() {
+  const paths = installPaths();
+  const settings = readSettings2(paths.claudeSettings);
+  console.log(`statusline: settings   ${paths.claudeSettings}`);
+  console.log(`statusline: command    ${statuslineCommand()}`);
+  const s = settings.statusLine;
+  if (!s) {
+    console.log("statusline: not registered (run `statusline install`).");
+    return 1;
+  }
+  if (!isOurStatusline(s)) {
+    console.log(`statusline: another statusLine is registered: ${JSON.stringify(s)}`);
+    return 1;
+  }
+  console.log("statusline: registered.");
+  return 0;
+}
+async function runStatusline(argv) {
+  const [sub = "status", ...rest2] = argv;
+  switch (sub) {
+    case "render":
+      return render2();
+    case "install":
+      return install2(rest2);
+    case "uninstall":
+      return uninstall2();
+    case "status":
+      return status2();
+    default:
+      console.error(`statusline: unknown subcommand "${sub}" (render | install | uninstall | status)`);
+      return 2;
+  }
+}
+
 // packages/cli/src/commands/install.ts
 function step(n, total, title) {
   console.log(`
@@ -41570,12 +42122,13 @@ async function setUpSearch(webapiUrl2) {
 async function runInstall(argv) {
   const { options } = parseFlags(argv);
   const noHook = options["no-hook"] === true;
+  const noStatusline = options["no-statusline"] === true;
   const noApp = options["no-app"] === true;
   const meiliKey = options["meili-key"] === true;
   const noPrune = options["no-prune"] === true;
   const portBaseOpt = strOpt(options, "port-base");
   const paths = installPaths();
-  const priorAppTag = existsSync8(paths.instanceEnv) ? /^APP_TAG=(\S+)\s*$/m.exec(readFileSync11(paths.instanceEnv, "utf8"))?.[1] : undefined;
+  const priorAppTag = existsSync9(paths.instanceEnv) ? /^APP_TAG=(\S+)\s*$/m.exec(readFileSync12(paths.instanceEnv, "utf8"))?.[1] : undefined;
   const TOTAL = 8;
   console.log(`claude-transcripts install (${VERSION})`);
   console.log(`  config  ${paths.configDir}`);
@@ -41603,7 +42156,7 @@ async function runInstall(argv) {
     portBase = found;
   }
   step(2, TOTAL, "Configuration");
-  const firstRun = !existsSync8(paths.instanceEnv);
+  const firstRun = !existsSync9(paths.instanceEnv);
   let env4 = loadOrCreateInstanceEnv(paths.instanceEnv, {
     portBase,
     appTag: VERSION === DEV_VERSION ? "main" : VERSION,
@@ -41687,6 +42240,10 @@ async function runInstall(argv) {
     console.log("  --no-hook: skipped registration");
   } else {
     await runHook(["install"]);
+    if (noStatusline)
+      console.log("  --no-statusline: skipped the statusline indicator");
+    else
+      await runStatusline(["install"]);
   }
   step(7, TOTAL, "Search");
   if (noApp) {
@@ -41761,10 +42318,10 @@ async function runMigrate(argv) {
 }
 
 // packages/cli/src/commands/provision.ts
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync10 } from "fs";
 async function runProvision(_argv) {
   const paths = installPaths();
-  if (!existsSync9(paths.instanceEnv)) {
+  if (!existsSync10(paths.instanceEnv)) {
     console.error("provision: this machine has no instance \u2014 run `claude-transcripts install` first.");
     return 1;
   }
@@ -41894,6 +42451,10 @@ async function runSearch(argv) {
       ...strOpt(options, "hostname") ? { hostname: strOpt(options, "hostname") } : {},
       ...strOpt(options, "source") ? { source: strOpt(options, "source") } : {}
     });
+    if (options.json === true) {
+      console.log(JSON.stringify(res, null, 2));
+      return res.enabled ? 0 : 1;
+    }
     if (!res.enabled) {
       console.error("search: search is not enabled on this instance.");
       console.error("search: turn on `features.meilisearch` in config/config.json, bring up the stack,");
@@ -41975,8 +42536,12 @@ function summaryLine(s) {
     [s.tokenUsage ? num3(s.tokenUsage.total) : "\u2014", 9]
   ], RIGHT_FROM);
 }
-async function showList(limit) {
+async function showList(limit, json) {
   const res = await listSessions({ limit });
+  if (json) {
+    console.log(JSON.stringify(res, null, 2));
+    return 0;
+  }
   console.log(`sessions: ${num3(res.totalCount)} total (${webapiUrl()})`);
   if (res.sessions.length === 0) {
     console.log("sessions: none recorded yet");
@@ -42001,8 +42566,13 @@ function entryLine(entry, i) {
   const preview = (text && tools2 ? `${text} ${tools2}` : text || tools2).replace(/\s+/g, " ").trim().slice(0, 100);
   return `  ${padL(`#${i}`, 4)}  ${pad2(entry.role, 12)} ${preview}`;
 }
-async function showDetail(id, limit) {
+async function showDetail(id, limit, json) {
   const s = await getSession(id);
+  if (json) {
+    const transcript = s.hasTranscript ? await getSessionTranscript(id, { limit }) : null;
+    console.log(JSON.stringify({ session: s, transcript }, null, 2));
+    return 0;
+  }
   console.log(`session ${s.sessionId}  [${s.status}]`);
   console.log(`  started    ${s.timestamp ?? "\u2014"}`);
   console.log(`  project    ${s.cwd || "\u2014"}`);
@@ -42034,8 +42604,9 @@ async function runSessions(argv) {
   const limitOpt = strOpt(options, "limit");
   const limit = limitOpt ? Number(limitOpt) : positionals[0] ? 30 : 50;
   const id = positionals[0];
+  const json = options.json === true;
   try {
-    return id ? await showDetail(id, limit) : await showList(limit);
+    return id ? await showDetail(id, limit, json) : await showList(limit, json);
   } catch (err) {
     console.error(`sessions: failed \u2014 ${err.message}`);
     console.error(`sessions: is the webapi reachable at ${webapiUrl()}? (set --webapi or $CT_WEBAPI_URL)`);
@@ -42044,9 +42615,9 @@ async function runSessions(argv) {
 }
 
 // packages/cli/src/commands/setup.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync7, readFileSync as readFileSync12, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync8, readFileSync as readFileSync13, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname5, join as join9 } from "path";
+import { dirname as dirname6, join as join9 } from "path";
 var REPO_ROOT = join9(import.meta.dir, "..", "..", "..", "..");
 var HOOK_DIR = join9(REPO_ROOT, "hooks");
 var HOOK_CONFIG_PATH = process.env.CT_HOOK_CONFIG ?? join9(homedir3(), ".config", "claude-transcripts", "config.json");
@@ -42055,7 +42626,7 @@ var PROJECT_SETTINGS = join9(process.cwd(), ".claude", "settings.json");
 function loadRepoConfig() {
   const live = join9(REPO_ROOT, "config", "config.json");
   const template2 = join9(REPO_ROOT, "config", "config.template.json");
-  return JSON.parse(readFileSync12(existsSync10(live) ? live : template2, "utf8"));
+  return JSON.parse(readFileSync13(existsSync11(live) ? live : template2, "utf8"));
 }
 function buildHookConfig2(cfg) {
   const env4 = process.env;
@@ -42120,9 +42691,9 @@ async function probeGarage(blob) {
     console.warn(`  garage bucket ${bucket}: NOT reachable/created \u2014 create it + a key on the Garage cluster (admin), then set S3_* in .env. (${err.message})`);
   }
 }
-function readSettings2(path) {
+function readSettings3(path) {
   try {
-    return JSON.parse(readFileSync12(path, "utf8"));
+    return JSON.parse(readFileSync13(path, "utf8"));
   } catch {
     return {};
   }
@@ -42132,13 +42703,13 @@ function dispatchCommand() {
 }
 function isRegistered(path) {
   const cmd = dispatchCommand();
-  const hooks2 = readSettings2(path).hooks ?? {};
+  const hooks2 = readSettings3(path).hooks ?? {};
   return Object.values(hooks2).some((groups) => groups.some((g) => g.hooks.some((h) => h.command === cmd)));
 }
 function registerGlobal(dryRun) {
   const cmd = dispatchCommand();
-  const generated = JSON.parse(readFileSync12(join9(HOOK_DIR, "hooks", "hooks.json"), "utf8"));
-  const settings = readSettings2(GLOBAL_SETTINGS);
+  const generated = JSON.parse(readFileSync13(join9(HOOK_DIR, "hooks", "hooks.json"), "utf8"));
+  const settings = readSettings3(GLOBAL_SETTINGS);
   const hooks2 = settings.hooks ?? {};
   for (const [event, groups] of Object.entries(generated.hooks)) {
     const timeout = groups[0]?.hooks[0]?.timeout;
@@ -42152,8 +42723,8 @@ function registerGlobal(dryRun) {
     console.log(`  [check] would register ${Object.keys(generated.hooks).length} events in ${GLOBAL_SETTINGS}`);
     return;
   }
-  mkdirSync7(dirname5(GLOBAL_SETTINGS), { recursive: true });
-  writeFileSync7(GLOBAL_SETTINGS, `${JSON.stringify({ ...settings, hooks: hooks2 }, null, 2)}
+  mkdirSync8(dirname6(GLOBAL_SETTINGS), { recursive: true });
+  writeFileSync8(GLOBAL_SETTINGS, `${JSON.stringify({ ...settings, hooks: hooks2 }, null, 2)}
 `);
   console.log(`  registered ${Object.keys(generated.hooks).length} events (system-wide) in ${GLOBAL_SETTINGS}`);
 }
@@ -42162,7 +42733,7 @@ function registerProject() {
 }
 function reportExisting() {
   const g = isRegistered(GLOBAL_SETTINGS);
-  const p = existsSync10(PROJECT_SETTINGS) && isRegistered(PROJECT_SETTINGS);
+  const p = existsSync11(PROJECT_SETTINGS) && isRegistered(PROJECT_SETTINGS);
   console.log(`  existing registration \u2192 global: ${g ? "yes" : "no"}, this project: ${p ? "yes" : "no"}`);
 }
 async function reportSearch() {
@@ -42193,7 +42764,7 @@ async function runSetup(argv) {
   reportExisting();
   if (check2) {
     console.log("setup --check (read-only):");
-    console.log(`  hook config: ${existsSync10(HOOK_CONFIG_PATH) ? "present" : "MISSING"} (${HOOK_CONFIG_PATH})`);
+    console.log(`  hook config: ${existsSync11(HOOK_CONFIG_PATH) ? "present" : "MISSING"} (${HOOK_CONFIG_PATH})`);
     console.log(`  couch: ${couch.url}`);
     await provisionCouch2(couch, true);
     await probeGarage(hookConfig.blob);
@@ -42216,12 +42787,12 @@ async function runSetup(argv) {
 }
 
 // packages/cli/src/commands/stack.ts
-import { existsSync as existsSync11 } from "fs";
+import { existsSync as existsSync12 } from "fs";
 async function runStack(argv) {
   const { positionals, options } = parseFlags(argv);
   const cmd = positionals[0] ?? "ps";
   const paths = installPaths();
-  if (!existsSync11(paths.instanceEnv)) {
+  if (!existsSync12(paths.instanceEnv)) {
     console.error("stack: this machine has no instance \u2014 run `claude-transcripts install` first.");
     return 1;
   }
@@ -42255,8 +42826,110 @@ async function runStack(argv) {
   }
 }
 
+// packages/cli/src/commands/turns.ts
+var ROLE_W2 = 11;
+function textWidth() {
+  const cols = process.stdout.columns ?? 0;
+  const before2 = 8 + 2 + 16 + 2 + ROLE_W2 + 2 + 18 + 2;
+  return Math.max(40, (cols > 0 ? cols : 120) - before2);
+}
+function oneLine(text, width) {
+  const t = text.replace(/\s+/g, " ").trim();
+  return t.length > width ? `${t.slice(0, width - 1)}\u2026` : t;
+}
+function crossTurnLine(t, width = textWidth()) {
+  return row([
+    [t.sessionId.slice(0, 8), 8],
+    [when(t.timestamp), 16],
+    [t.role, ROLE_W2],
+    [project2(t.cwd), 18],
+    [oneLine(t.text, width), width]
+  ]);
+}
+function sessionTurnLine(t, i, width = textWidth()) {
+  const tools2 = (t.toolUses ?? []).map((u) => `\u2699 ${u.name}`).join(" ");
+  const text = t.text ?? "";
+  return row([
+    [`#${i}`, 5],
+    [when(t.timestamp), 16],
+    [t.role, ROLE_W2],
+    [oneLine(text && tools2 ? `${text} ${tools2}` : text || tools2, width), width]
+  ]);
+}
+async function runTurns(argv) {
+  const { positionals, options } = parseFlags(argv);
+  const webapiOverride = strOpt(options, "webapi");
+  if (webapiOverride)
+    setWebapiUrl(webapiOverride);
+  const json = options.json === true;
+  const role = strOpt(options, "role");
+  const limitOpt = strOpt(options, "limit");
+  const limit = limitOpt ? Number(limitOpt) : 50;
+  const id = positionals[0];
+  try {
+    if (id) {
+      const offsetOpt = strOpt(options, "skip");
+      const res2 = await getSessionTurns(id, {
+        ...role ? { role } : {},
+        limit,
+        ...offsetOpt ? { offset: Number(offsetOpt) } : {}
+      });
+      if (json) {
+        console.log(JSON.stringify(res2, null, 2));
+        return 0;
+      }
+      console.log(`turns: session ${id.slice(0, 8)} \u2014 ${num3(res2.turns.length)} of ${num3(res2.totalCount)}${role ? ` (${role})` : ""} (${webapiUrl()})`);
+      const width2 = textWidth();
+      console.log(row([
+        ["#", 5],
+        ["WHEN", 16],
+        ["WHO", ROLE_W2],
+        ["TEXT", width2]
+      ]));
+      for (const [i, t] of res2.turns.entries())
+        console.log(sessionTurnLine(t, i, width2));
+      return 0;
+    }
+    const skipOpt = strOpt(options, "skip");
+    const res = await getTurns({
+      ...role ? { role } : {},
+      ...strOpt(options, "from") ? { from: strOpt(options, "from") } : {},
+      ...strOpt(options, "to") ? { to: strOpt(options, "to") } : {},
+      limit,
+      ...skipOpt ? { skip: Number(skipOpt) } : {}
+    });
+    if (json) {
+      console.log(JSON.stringify(res, null, 2));
+      return 0;
+    }
+    console.log(`turns: ${num3(res.turns.length)}${res.hasMore ? "+" : ""}${role ? ` (${role})` : ""}, all sessions, time order (${webapiUrl()})`);
+    if (res.turns.length === 0) {
+      console.log("turns: none \u2014 sessions logged without couchFullContentChunks have no turns");
+      return 0;
+    }
+    const width = textWidth();
+    console.log(row([
+      ["SESSION", 8],
+      ["WHEN", 16],
+      ["WHO", ROLE_W2],
+      ["PROJECT", 18],
+      ["TEXT", width]
+    ]));
+    for (const t of res.turns)
+      console.log(crossTurnLine(t, width));
+    if (res.hasMore)
+      console.log(`
+\u2026 more \u2014 raise --limit, or page with --skip`);
+    return 0;
+  } catch (err) {
+    console.error(`turns: failed \u2014 ${err.message}`);
+    console.error(`turns: is the webapi reachable at ${webapiUrl()}? (set --webapi or $CT_WEBAPI_URL)`);
+    return 1;
+  }
+}
+
 // packages/cli/src/commands/uninstall.ts
-import { existsSync as existsSync12, rmSync } from "fs";
+import { existsSync as existsSync13, rmSync } from "fs";
 async function confirmPurge(auto) {
   if (auto)
     return true;
@@ -42276,7 +42949,7 @@ async function runUninstall(argv) {
   }
   console.log("uninstall: deregistering the hook");
   await runHook(["uninstall"]);
-  if (existsSync12(paths.instanceEnv)) {
+  if (existsSync13(paths.instanceEnv)) {
     console.log(`uninstall: stopping the stack${purge ? " and deleting volumes" : ""}`);
     try {
       const env4 = loadOrCreateInstanceEnv(paths.instanceEnv);
@@ -42309,6 +42982,7 @@ var COMMANDS = {
   stack: runStack,
   provision: runProvision,
   hook: runHook,
+  statusline: runStatusline,
   export: runExport,
   import: runImport,
   setup: runSetup,
@@ -42317,7 +42991,8 @@ var COMMANDS = {
   reindex: runReindex,
   doctor: runDoctor,
   sessions: runSessions,
-  search: runSearch
+  search: runSearch,
+  turns: runTurns
 };
 
 // packages/cli/src/app.tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-transcripts/cli",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "type": "module",
   "description": "Claude Transcripts CLI — browse, search, back up, and administer your self-hosted Claude Code session history.",
   "keywords": [