backthread 0.1.4 → 0.2.1

package/.claude-plugin/plugin.json

@@ -1,11 +1,17 @@
 {
   "name": "backthread",
   "displayName": "Backthread",
-  "description": "Keep the thread on what the agent shipped: Backthread captures the \"why\" of every session and answers \"how does X work?\" on a live \"how it works\" diagram — no diving through PRs. Provides the /backthread:capture slash command, the SessionEnd capture hook, and the backthread MCP server (capture + query).",
-  "version": "0.1.0",
+  "description": "Backthread helps you understand your codebase while AI ships features. It captures the why behind every Claude Code session so you can ask \"how does X work?\" without digging through PRs.",
+  "version": "0.2.1",
   "author": {
     "name": "Backthread"
   },
   "homepage": "https://backthread.dev",
-  "hooks": "./hooks/hooks.json"
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": {
+    "backthread": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist-bundle/backthread.js", "mcp"]
+    }
+  }
 }

package/README.md

@@ -38,6 +38,24 @@ can verify it — read more at [backthread.dev/security](https://backthread.dev/
 
 ## Quick start
 
+### Claude Code → install the plugin (one click, recommended)
+
+In Claude Code:
+
+```
+/plugin marketplace add backthread/backthread
+/plugin install backthread@backthread
+/backthread:start
+```
+
+Installing the plugin bundles the CLI — no separate npm step — and registers, at
+**user/global scope** (so it works across every repo and git worktree), the
+SessionEnd **capture hook**, the `/backthread:capture` & `/backthread:start`
+commands, and the **backthread MCP server** (capture + `query`). `/backthread:start`
+just signs you in. That's the whole setup.
+
+### Any agent (or bare terminal) → `npx backthread install`
+
 In your project:
 
 ```bash
@@ -57,6 +75,23 @@ That's the whole setup. `install`:
 Already added Backthread as a Claude Code plugin? The hook is wired for you —
 run `/backthread:start` (or `npx backthread start`) just to sign in.
 
+### Codex / Cursor / Gemini CLI → `npx backthread install --agent <agent>`
+
+Use another coding agent? One command wires up its **MCP server** (the `query`
+tool) **and** an automatic capture hook — written to that agent's **user-global**
+config so capture follows you across every repo and git worktree:
+
+```bash
+npx backthread install --agent codex     # ~/.codex/config.toml + ~/.codex/hooks.json
+npx backthread install --agent cursor     # ~/.cursor/mcp.json   + ~/.cursor/hooks.json
+npx backthread install --agent gemini     # ~/.gemini/settings.json (MCP + SessionEnd hook)
+```
+
+It's idempotent (re-running never duplicates anything) and a strict merge (it never
+clobbers your other config). Then `npx backthread login` once to authorize. Gemini
+users can also install the [one-command extension](https://github.com/backthread/backthread/tree/main/extensions/gemini)
+instead, and Codex users the [plugin](https://github.com/backthread/backthread/tree/main/extensions/codex).
+
 ## Onboard yourself in 3 steps
 
 1. **Install** — `npx backthread install` in your repo. One browser click to authorize.

package/commands/capture.md

@@ -17,7 +17,7 @@ summary tells you to re-run with an explicit path:
 
 ## Capture result
 
-!`npx backthread capture --manual --session "${CLAUDE_SESSION_ID}" --cwd "$(pwd)" $ARGUMENTS`
+!`BT="${CLAUDE_PLUGIN_ROOT}/dist-bundle/backthread.js"; if [ -f "$BT" ]; then node "$BT" capture --manual --session "${CLAUDE_SESSION_ID}" --cwd "$(pwd)" $ARGUMENTS; else npx backthread capture --manual --session "${CLAUDE_SESSION_ID}" --cwd "$(pwd)" $ARGUMENTS; fi`
 
 ## Your task
 

package/commands/start.md

@@ -16,7 +16,7 @@ If the web app handed you a claim code, pass it: `/backthread:start --claim <cod
 
 ## Setup result
 
-!`npx backthread start $ARGUMENTS`
+!`BT="${CLAUDE_PLUGIN_ROOT}/dist-bundle/backthread.js"; if [ -f "$BT" ]; then node "$BT" start $ARGUMENTS; else npx backthread start $ARGUMENTS; fi`
 
 ## Your task
 

package/dist-bundle/backthread.js

@@ -7289,7 +7289,7 @@ async function ensureAuth(opts = {}) {
 }
 
 // src/capture.ts
-import { readFile as readFile5 } from "node:fs/promises";
+import { readFile as readFile8 } from "node:fs/promises";
 
 // ../packages/redact/src/index.ts
 var CODE_REDACTION = "[code redacted]";
@@ -7717,17 +7717,13 @@ async function maybeNudge(status, repo, sessionId, deps = {}) {
 }
 
 // src/firstRun.ts
-import { join as join7 } from "node:path";
-import { readFile as readFile4, writeFile as writeFile4, mkdir as mkdir4, chmod as chmod3 } from "node:fs/promises";
+import { join as join9 } from "node:path";
+import { readFile as readFile7, writeFile as writeFile6, mkdir as mkdir6, chmod as chmod4 } from "node:fs/promises";
 
 // src/install.ts
-import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3 } from "node:fs/promises";
-import { join as join6 } from "node:path";
-
-// src/backfill.ts
-import { readdir } from "node:fs/promises";
-import { homedir as homedir3 } from "node:os";
-import { join as join5 } from "node:path";
+import { readFile as readFile6, writeFile as writeFile5, mkdir as mkdir5 } from "node:fs/promises";
+import { homedir as homedir5 } from "node:os";
+import { join as join8 } from "node:path";
 
 // src/captureCommand.ts
 import { stat } from "node:fs/promises";
@@ -7837,9 +7833,135 @@ function parseManualArgs(argv) {
   return { manual, input };
 }
 
-// src/backfill.ts
-function claudeProjectsDir(cwd, home) {
-  return join5(home, ".claude", "projects", slugifyCwd(cwd));
+// src/sweep.ts
+import { readFile as readFile4, stat as stat2, readdir } from "node:fs/promises";
+import { execFileSync as execFileSync2 } from "node:child_process";
+import { homedir as homedir3 } from "node:os";
+import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join6 } from "node:path";
+
+// src/sweepLedger.ts
+import { join as join5 } from "node:path";
+import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3, chmod as chmod3 } from "node:fs/promises";
+var MAX_PROCESSED = 2e4;
+function sweepStatePath(env = process.env) {
+  return join5(configDir(env), "sweep-state.json");
+}
+function parseSweepState(raw) {
+  try {
+    const obj = JSON.parse(raw);
+    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+      const rec = obj;
+      const processed = Array.isArray(rec.processed) ? rec.processed.filter((s) => typeof s === "string") : [];
+      const lastSweptAt = {};
+      if (rec.lastSweptAt && typeof rec.lastSweptAt === "object" && !Array.isArray(rec.lastSweptAt)) {
+        for (const [k, v] of Object.entries(rec.lastSweptAt)) {
+          if (typeof v === "string" && v.length > 0) lastSweptAt[k] = v;
+        }
+      }
+      return { processed, lastSweptAt };
+    }
+  } catch {
+  }
+  return { processed: [], lastSweptAt: {} };
+}
+function serializeSweepState(state) {
+  return JSON.stringify({ processed: state.processed, lastSweptAt: state.lastSweptAt }) + "\n";
+}
+async function readSweepState(env = process.env) {
+  try {
+    return parseSweepState(await readFile3(sweepStatePath(env), "utf8"));
+  } catch {
+    return { processed: [], lastSweptAt: {} };
+  }
+}
+async function writeSweepState(state, env = process.env) {
+  try {
+    const dir = configDir(env);
+    await mkdir3(dir, { recursive: true, mode: DIR_MODE });
+    await chmod3(dir, DIR_MODE).catch(() => {
+    });
+    const path = sweepStatePath(env);
+    await writeFile3(path, serializeSweepState(state), { mode: CONFIG_MODE });
+    await chmod3(path, CONFIG_MODE).catch(() => {
+    });
+  } catch {
+  }
+}
+function addProcessed(state, sessionIds) {
+  const seen = new Set(state.processed);
+  const next = [...state.processed];
+  for (const sid of sessionIds) {
+    if (!sid || seen.has(sid)) continue;
+    seen.add(sid);
+    next.push(sid);
+  }
+  if (next.length > MAX_PROCESSED) next.splice(0, next.length - MAX_PROCESSED);
+  return { ...state, processed: next };
+}
+async function markSweepProcessed(sessionId, env = process.env) {
+  if (!sessionId || sessionId.trim().length === 0) return;
+  try {
+    const state = await readSweepState(env);
+    if (state.processed.includes(sessionId)) return;
+    await writeSweepState(addProcessed(state, [sessionId]), env);
+  } catch {
+  }
+}
+
+// src/sweep.ts
+var SWEEP_DEBOUNCE_MS = 15 * 60 * 1e3;
+var EMPTY = (status, repo, text) => ({
+  status,
+  repo,
+  dirsSwept: 0,
+  found: 0,
+  skipped: 0,
+  captured: 0,
+  decisions: 0,
+  attributions: [],
+  text
+});
+function isTerminallyProcessed(outcome) {
+  return outcome.status === "persisted" || outcome.status === "persisted-by-server" || outcome.status === "nothing-to-capture";
+}
+function syntheticRemote(repo) {
+  return `https://github.com/${repo.owner}/${repo.name}.git`;
+}
+function extractCwdFromRaw(raw) {
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let rec;
+    try {
+      rec = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (!rec || typeof rec !== "object") continue;
+    const r = rec;
+    if (typeof r.cwd === "string" && r.cwd.trim().length > 0) return r.cwd.trim();
+    if (r.type === "session_meta" && typeof r.payload?.cwd === "string" && r.payload.cwd.trim().length > 0) {
+      return r.payload.cwd.trim();
+    }
+  }
+  return null;
+}
+function classifyDir(args) {
+  const { dirName, mainSlug, mainRoot, embeddedCwd, cwdExists, resolved, target } = args;
+  if (dirName !== mainSlug && !dirName.startsWith(mainSlug + "-")) {
+    return { include: false, mode: "unattributable", cwd: embeddedCwd };
+  }
+  if (!embeddedCwd) return { include: false, mode: "unattributable", cwd: null };
+  if (cwdExists) {
+    if (resolved && resolved.owner === target.owner && resolved.name === target.name) {
+      return { include: true, mode: "git", cwd: embeddedCwd };
+    }
+    return { include: false, mode: "excluded-other-repo", cwd: embeddedCwd };
+  }
+  const isNested = embeddedCwd === mainRoot || embeddedCwd.startsWith(mainRoot + "/");
+  const isSibling = embeddedCwd.startsWith(mainRoot + "-");
+  if (isNested || isSibling) return { include: true, mode: "heuristic", cwd: embeddedCwd };
+  return { include: false, mode: "unattributable", cwd: embeddedCwd };
 }
 async function defaultReadDir(dir) {
   try {
@@ -7848,53 +7970,412 @@ async function defaultReadDir(dir) {
     return [];
   }
 }
-async function runBackfill(input = {}, deps = {}) {
-  const log = deps.log ?? ((m) => console.error(m));
-  const home = (deps.homedirImpl ?? homedir3)();
-  const cwd = input.cwd ?? process.cwd();
-  const doReadDir = deps.readDirImpl ?? defaultReadDir;
-  const run = deps.runCaptureImpl ?? runCapture;
-  const dir = claudeProjectsDir(cwd, home);
-  let entries;
+async function defaultPathExists(path) {
   try {
-    entries = await doReadDir(dir);
+    await stat2(path);
+    return true;
   } catch {
-    entries = [];
-  }
-  const files = entries.filter((n) => n.endsWith(".jsonl")).sort();
-  if (files.length === 0) {
-    const text2 = "backthread backfill: no past Claude Code sessions found for this repo \u2014 nothing to backfill. Live capture is armed; your decision log fills as you work.";
-    log(text2);
-    return { found: 0, captured: 0, decisions: 0, results: [], text: text2 };
+    return false;
   }
-  log(
-    `backthread backfill: found ${files.length} past Claude Code session(s) for this repo \u2014 seeding your decision log (best-effort, this never blocks)\u2026`
-  );
-  const results = [];
-  let captured = 0;
-  let decisions = 0;
-  for (const file2 of files) {
-    const hookInput = {
-      transcript_path: join5(dir, file2),
+}
+function defaultMainRoot(cwd) {
+  try {
+    const out = execFileSync2("git", ["rev-parse", "--git-common-dir"], {
       cwd,
-      hook_event_name: "SessionEnd"
-    };
-    let outcome;
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (!out) return null;
+    const abs = isAbsolute2(out) ? out : join6(cwd, out);
+    return dirname2(abs.replace(/\/+$/, ""));
+  } catch {
+    return null;
+  }
+}
+async function runSweep(input = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const log = deps.log ?? ((m) => console.error(m));
+  const debounceMs = deps.debounceMs ?? SWEEP_DEBOUNCE_MS;
+  const baseReadDir = deps.readDirImpl ?? defaultReadDir;
+  const doReadDir = async (d) => {
     try {
-      outcome = await run(hookInput, deps.captureDeps);
-    } catch (e) {
-      outcome = { status: "error", detail: `capture threw (swallowed): ${e.message}` };
+      return await baseReadDir(d);
+    } catch {
+      return [];
     }
-    results.push({ file: file2, outcome });
-    if (outcome.status === "persisted" || outcome.status === "persisted-by-server") {
-      captured += 1;
-      decisions += typeof outcome.count === "number" ? outcome.count : 0;
+  };
+  const baseReadFile = deps.readFileImpl ?? ((p) => readFile4(p, "utf8"));
+  const doReadFile = async (p) => {
+    try {
+      return await baseReadFile(p);
+    } catch {
+      return "";
     }
-    log(`  ${file2}: ${outcome.status}${typeof outcome.count === "number" ? ` (${outcome.count})` : ""}`);
+  };
+  const basePathExists = deps.pathExistsImpl ?? defaultPathExists;
+  const doPathExists = async (p) => {
+    try {
+      return await basePathExists(p);
+    } catch {
+      return false;
+    }
+  };
+  const doMainRoot = (c) => {
+    try {
+      return (deps.mainRootImpl ?? defaultMainRoot)(c);
+    } catch {
+      return null;
+    }
+  };
+  const readRemote = deps.readRemoteImpl;
+  const doReadConfig = deps.readConfigImpl ?? readConfig;
+  const run = deps.runCaptureImpl ?? runCapture;
+  const doReadState = deps.readSweepStateImpl ?? readSweepState;
+  const doWriteState = deps.writeSweepStateImpl ?? writeSweepState;
+  try {
+    const home = (deps.homedirImpl ?? homedir3)();
+    const now = (deps.nowImpl ?? (() => (/* @__PURE__ */ new Date()).toISOString()))();
+    const cwd = input.cwd ?? process.cwd();
+    const target = resolveRepo(cwd, readRemote);
+    if (!target) {
+      const text2 = `backthread sweep: no git remote for ${cwd} \u2014 can't scope a gap-recovery sweep.`;
+      log(text2);
+      return EMPTY("no-repo", null, text2);
+    }
+    const repoSlug = `${target.owner}/${target.name}`;
+    const config2 = await Promise.resolve().then(() => doReadConfig(env)).catch(() => ({}));
+    if (!config2.device_token) {
+      const text2 = `backthread sweep: not logged in \u2014 skipping gap recovery for ${repoSlug}.`;
+      log(text2);
+      return EMPTY("no-auth", repoSlug, text2);
+    }
+    const state = await doReadState(env).catch(() => ({ processed: [], lastSweptAt: {} }));
+    if (!input.force) {
+      const last = state.lastSweptAt[repoSlug];
+      if (last) {
+        const age = Date.parse(now) - Date.parse(last);
+        if (Number.isFinite(age) && age >= 0 && age < debounceMs) {
+          return EMPTY("debounced", repoSlug, `backthread sweep: ${repoSlug} swept recently \u2014 skipped.`);
+        }
+      }
+    }
+    const mainRoot = doMainRoot(cwd) ?? cwd;
+    const mainSlug = slugifyCwd(mainRoot);
+    const projectsRoot = join6(home, ".claude", "projects");
+    const entries = await doReadDir(projectsRoot);
+    const candidates = entries.filter((n) => n === mainSlug || n.startsWith(mainSlug + "-")).sort();
+    const skip = new Set(state.processed);
+    for (const sid of input.knownCapturedSessionIds ?? []) if (sid) skip.add(sid);
+    const attributions = [];
+    const newlyProcessed = [];
+    let dirsSwept = 0;
+    let found = 0;
+    let skipped = 0;
+    let captured = 0;
+    let decisions = 0;
+    for (const dirName of candidates) {
+      const dir = join6(projectsRoot, dirName);
+      const files = (await doReadDir(dir)).filter((n) => n.endsWith(".jsonl")).sort();
+      if (files.length === 0) continue;
+      let embeddedCwd = null;
+      for (const file2 of files) {
+        embeddedCwd = extractCwdFromRaw(await doReadFile(join6(dir, file2)));
+        if (embeddedCwd) break;
+      }
+      const cwdExists = embeddedCwd ? await doPathExists(embeddedCwd) : false;
+      const resolved = embeddedCwd && cwdExists ? resolveRepo(embeddedCwd, readRemote) : null;
+      const cls = classifyDir({ dirName, mainSlug, mainRoot, embeddedCwd, cwdExists, resolved, target });
+      attributions.push({ dir: dirName, mode: cls.mode, cwd: cls.cwd, transcripts: files.length });
+      if (!cls.include) {
+        if (cls.mode === "unattributable") {
+          log(
+            `backthread sweep: ${files.length} transcript(s) in ${dirName} can't be attributed to ${repoSlug}` + (cls.cwd ? ` (cwd ${cls.cwd} is gone)` : " (no cwd recorded)") + " \u2014 left for GitHub-derived recovery (ARP-538)."
+          );
+        }
+        continue;
+      }
+      if (cls.mode === "heuristic") {
+        log(
+          `backthread sweep: attributing ${files.length} transcript(s) in deleted-worktree dir ${dirName} to ${repoSlug} by path heuristic (cwd ${cls.cwd} no longer exists).`
+        );
+      }
+      dirsSwept += 1;
+      const captureDeps = {
+        ...deps.captureDeps,
+        readRemoteImpl: () => syntheticRemote(target),
+        // A silent background sweep must NEVER pop a browser login.
+        ensureAuthImpl: deps.captureDeps?.ensureAuthImpl ?? (() => {
+        })
+      };
+      for (const file2 of files) {
+        const sid = basename(file2, ".jsonl");
+        if (skip.has(sid)) {
+          skipped += 1;
+          continue;
+        }
+        found += 1;
+        let outcome;
+        try {
+          outcome = await run(
+            {
+              transcript_path: join6(dir, file2),
+              cwd: cls.cwd ?? mainRoot,
+              session_id: sid,
+              hook_event_name: "SessionEnd"
+            },
+            captureDeps
+          );
+        } catch (e) {
+          outcome = { status: "error", detail: `capture threw (swallowed): ${e.message}` };
+        }
+        if (outcome.status === "persisted" || outcome.status === "persisted-by-server") {
+          captured += 1;
+          decisions += typeof outcome.count === "number" ? outcome.count : 0;
+        }
+        if (isTerminallyProcessed(outcome)) {
+          newlyProcessed.push(sid);
+          skip.add(sid);
+        }
+        log(`  ${dirName}/${file2}: ${outcome.status}${typeof outcome.count === "number" ? ` (${outcome.count})` : ""}`);
+      }
+    }
+    const nextState = addProcessed(state, newlyProcessed);
+    nextState.lastSweptAt = { ...nextState.lastSweptAt, [repoSlug]: now };
+    await doWriteState(nextState, env).catch(() => {
+    });
+    const text = `backthread sweep: ${repoSlug} \u2014 swept ${dirsSwept} dir(s), recovered ${decisions} decision(s) from ${captured} session(s) (${found} processed, ${skipped} already captured).`;
+    log(text);
+    return {
+      status: "swept",
+      repo: repoSlug,
+      dirsSwept,
+      found,
+      skipped,
+      captured,
+      decisions,
+      attributions,
+      text
+    };
+  } catch (e) {
+    const text = `backthread sweep: failed (swallowed) \u2014 ${e.message}`;
+    log(text);
+    return EMPTY("error", null, text);
   }
-  const text = `backthread backfill: processed ${files.length} session(s), captured ${decisions} decision(s) from ${captured} session(s). Your "How it works" log is no longer empty.`;
-  log(text);
-  return { found: files.length, captured, decisions, results, text };
+}
+async function runGapRecoverySweep(input = {}, deps = {}) {
+  return runSweep({ ...input, force: input.force ?? false }, deps);
+}
+
+// src/backfill.ts
+async function runBackfill(input = {}, deps = {}) {
+  const summary = await runSweep({ cwd: input.cwd, force: true }, deps);
+  return {
+    found: summary.found,
+    captured: summary.captured,
+    decisions: summary.decisions,
+    results: [],
+    text: summary.text
+  };
+}
+
+// src/installAgent.ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { homedir as homedir4 } from "node:os";
+import { join as join7, dirname as dirname3 } from "node:path";
+import { readFile as readFile5, writeFile as writeFile4, mkdir as mkdir4 } from "node:fs/promises";
+var execFileP = promisify(execFile);
+var MCP_COMMAND = "npx";
+var MCP_ARGS = ["-y", "backthread", "mcp"];
+function hookCommand(agent) {
+  return `npx -y backthread capture --from-hook --agent ${agent} --detach`;
+}
+var MIN_VERSION = {
+  codex: "0.124.0",
+  cursor: "1.7.0",
+  gemini: "0.26.0"
+};
+var VERSION_BIN = {
+  codex: "codex",
+  cursor: "cursor-agent",
+  gemini: "gemini"
+};
+async function loadJsonObject(readFileImpl, path) {
+  let raw;
+  try {
+    raw = await readFileImpl(path);
+  } catch (e) {
+    if (isNotFound2(e)) return {};
+    throw e;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${path} exists but is not valid JSON \u2014 refusing to overwrite it. Fix it (or add the config manually) and re-run.`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${path} is not a JSON object \u2014 refusing to overwrite it. Fix it (or add the config manually) and re-run.`);
+  }
+  return parsed;
+}
+function isNotFound2(err) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+function asObject(v) {
+  return v && typeof v === "object" && !Array.isArray(v) ? { ...v } : {};
+}
+function mcpServerEntry() {
+  return { command: MCP_COMMAND, args: [...MCP_ARGS] };
+}
+function withMcpServer(settings) {
+  const mcpServers = asObject(settings.mcpServers);
+  const desired = mcpServerEntry();
+  if (JSON.stringify(mcpServers.backthread) === JSON.stringify(desired)) {
+    return { next: settings, changed: false };
+  }
+  mcpServers.backthread = desired;
+  return { next: { ...settings, mcpServers }, changed: true };
+}
+function withNestedHook(settings, event, command, extra = {}) {
+  const hooks = asObject(settings.hooks);
+  const list = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
+  const present = list.some((g) => {
+    const inner = g?.hooks;
+    return Array.isArray(inner) && inner.some((h) => h?.command === command);
+  });
+  if (present) return { next: settings, changed: false };
+  list.push({ hooks: [{ type: "command", command, ...extra }] });
+  hooks[event] = list;
+  return { next: { ...settings, hooks }, changed: true };
+}
+async function writeJson(deps, path, obj) {
+  const doMkdir = deps.mkdirImpl ?? (async (d) => void await mkdir4(d, { recursive: true }));
+  const doWrite = deps.writeFileImpl ?? ((p, d) => writeFile4(p, d));
+  await doMkdir(dirname3(path));
+  await doWrite(path, JSON.stringify(obj, null, 2) + "\n");
+}
+async function installGemini(home, deps) {
+  const doRead = deps.readFileImpl ?? ((p) => readFile5(p, "utf8"));
+  const path = join7(home, ".gemini", "settings.json");
+  const current = await loadJsonObject(doRead, path);
+  const a = withMcpServer(current);
+  const b = withNestedHook(a.next, "SessionEnd", hookCommand("gemini-cli"), { name: "backthread-capture" });
+  if (a.changed || b.changed) await writeJson(deps, path, b.next);
+  return [{ path, wrote: a.changed || b.changed }];
+}
+async function installCodex(home, deps) {
+  const doRead = deps.readFileImpl ?? ((p) => readFile5(p, "utf8"));
+  const writes = [];
+  const tomlPath = join7(home, ".codex", "config.toml");
+  let toml = "";
+  try {
+    toml = await doRead(tomlPath);
+  } catch (e) {
+    if (!isNotFound2(e)) throw e;
+  }
+  if (toml.includes("[mcp_servers.backthread]")) {
+    writes.push({ path: tomlPath, wrote: false });
+  } else {
+    const block = `[mcp_servers.backthread]
+command = "${MCP_COMMAND}"
+args = [${MCP_ARGS.map((a) => `"${a}"`).join(", ")}]
+`;
+    const sep = toml.length === 0 ? "" : toml.endsWith("\n") ? "\n" : "\n\n";
+    const doMkdir = deps.mkdirImpl ?? (async (d) => void await mkdir4(d, { recursive: true }));
+    const doWrite = deps.writeFileImpl ?? ((p, d) => writeFile4(p, d));
+    await doMkdir(dirname3(tomlPath));
+    await doWrite(tomlPath, toml + sep + block);
+    writes.push({ path: tomlPath, wrote: true });
+  }
+  const hooksPath = join7(home, ".codex", "hooks.json");
+  const current = await loadJsonObject(doRead, hooksPath);
+  const h = withNestedHook(current, "Stop", hookCommand("codex"), { timeout: 60 });
+  if (h.changed) await writeJson(deps, hooksPath, h.next);
+  writes.push({ path: hooksPath, wrote: h.changed });
+  return writes;
+}
+async function installCursor(home, deps) {
+  const doRead = deps.readFileImpl ?? ((p) => readFile5(p, "utf8"));
+  const writes = [];
+  const mcpPath = join7(home, ".cursor", "mcp.json");
+  const mcpCurrent = await loadJsonObject(doRead, mcpPath);
+  const m = withMcpServer(mcpCurrent);
+  if (m.changed) await writeJson(deps, mcpPath, m.next);
+  writes.push({ path: mcpPath, wrote: m.changed });
+  const hooksPath = join7(home, ".cursor", "hooks.json");
+  const hooksCurrent = await loadJsonObject(doRead, hooksPath);
+  const c = withCursorStopHook(hooksCurrent);
+  if (c.changed) await writeJson(deps, hooksPath, c.next);
+  writes.push({ path: hooksPath, wrote: c.changed });
+  return writes;
+}
+function withCursorStopHook(settings) {
+  const command = hookCommand("cursor");
+  const hooks = asObject(settings.hooks);
+  const stop = Array.isArray(hooks.stop) ? [...hooks.stop] : [];
+  const present = stop.some((h) => h?.command === command);
+  const hasVersion = typeof settings.version === "number";
+  if (present && hasVersion) return { next: settings, changed: false };
+  if (!present) stop.push({ command });
+  hooks.stop = stop;
+  return { next: { ...settings, version: hasVersion ? settings.version : 1, hooks }, changed: true };
+}
+function cursorDeeplink() {
+  const config2 = Buffer.from(JSON.stringify(mcpServerEntry())).toString("base64");
+  return `cursor://anysphere.cursor-deeplink/mcp/install?name=backthread&config=${config2}`;
+}
+function parseSemver(s) {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(s);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function isBelow(a, b) {
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i];
+  return false;
+}
+async function probeVersion(agent) {
+  try {
+    const { stdout } = await execFileP(VERSION_BIN[agent], ["--version"], { timeout: 3e3 });
+    return stdout?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+async function versionGate(agent, deps) {
+  const probe = deps.probeVersionImpl ?? probeVersion;
+  const raw = await probe(agent).catch(() => null);
+  if (!raw) return null;
+  const got = parseSemver(raw);
+  const min = parseSemver(MIN_VERSION[agent]);
+  if (got && isBelow(got, min)) {
+    return `Detected ${agent} ${got.join(".")}, but the capture hook needs ${MIN_VERSION[agent]}+. The MCP query tool works now; upgrade ${agent} for auto-capture.`;
+  }
+  return null;
+}
+async function runInstallAgent(agent, deps = {}) {
+  const home = deps.home ?? homedir4();
+  const versionWarning = await versionGate(agent, deps);
+  let writes;
+  switch (agent) {
+    case "gemini":
+      writes = await installGemini(home, deps);
+      break;
+    case "codex":
+      writes = await installCodex(home, deps);
+      break;
+    case "cursor":
+      writes = await installCursor(home, deps);
+      break;
+  }
+  return { agent, writes, versionWarning, deeplink: agent === "cursor" ? cursorDeeplink() : null };
+}
+function parseInstallAgent(value) {
+  if (!value) return null;
+  const v = value.trim().toLowerCase();
+  if (v === "claude-code" || v === "claude" || v === "cc") return "claude-code";
+  if (v === "gemini" || v === "gemini-cli") return "gemini";
+  if (v === "codex" || v === "cursor") return v;
+  return null;
 }
 
 // src/install.ts
@@ -7910,18 +8391,19 @@ var TRUST_COPY = [
 var HOOK_COMMAND = "npx backthread capture --from-hook --agent claude-code --detach";
 var LEGACY_HOOK_COMMANDS = ["npx backthread capture"];
 var OUR_HOOK_COMMANDS = /* @__PURE__ */ new Set([HOOK_COMMAND, ...LEGACY_HOOK_COMMANDS]);
-async function registerHook(cwd, deps = {}) {
-  const doReadFile = deps.readFileImpl ?? ((p) => readFile3(p, "utf8"));
-  const doWriteFile = deps.writeFileImpl ?? ((p, d) => writeFile3(p, d));
-  const doMkdir = deps.mkdirImpl ?? (async (d) => void await mkdir3(d, { recursive: true }));
-  const settingsDir = join6(cwd, ".claude");
-  const settingsPath = join6(settingsDir, "settings.json");
+async function registerHook(deps = {}) {
+  const doReadFile = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
+  const doWriteFile = deps.writeFileImpl ?? ((p, d) => writeFile5(p, d));
+  const doMkdir = deps.mkdirImpl ?? (async (d) => void await mkdir5(d, { recursive: true }));
+  const home = deps.home ?? homedir5();
+  const settingsDir = join8(home, ".claude");
+  const settingsPath = join8(settingsDir, "settings.json");
   let settings = {};
   let raw = null;
   try {
     raw = await doReadFile(settingsPath);
   } catch (e) {
-    if (!isNotFound2(e)) throw e;
+    if (!isNotFound3(e)) throw e;
     raw = null;
   }
   if (raw !== null) {
@@ -7949,7 +8431,7 @@ async function registerHook(cwd, deps = {}) {
   await doWriteFile(settingsPath, JSON.stringify(merged, null, 2) + "\n");
   return { wrote: true, path: settingsPath };
 }
-function isNotFound2(err) {
+function isNotFound3(err) {
   return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
 }
 function mergeSessionEndHook(settings) {
@@ -8016,12 +8498,36 @@ async function runInstall(opts = {}, deps = {}) {
       log("      Run `backthread login` to authorize, then re-run `backthread install`.");
     }
   }
+  const targetAgent = opts.agent && opts.agent !== "claude-code" ? opts.agent : null;
+  if (targetAgent) {
+    const doAgent = deps.runInstallAgentImpl ?? runInstallAgent;
+    let agentResult = null;
+    try {
+      agentResult = await doAgent(targetAgent, deps.agentDeps);
+      if (agentResult.versionWarning) log(`      \u26A0 ${agentResult.versionWarning}`);
+      for (const w of agentResult.writes) {
+        log(
+          w.wrote ? `[2/2] ${targetAgent}: configured ${w.path}.` : `[2/2] ${targetAgent}: already configured in ${w.path} (no change).`
+        );
+      }
+      if (agentResult.deeplink) log(`      One-click MCP install: ${agentResult.deeplink}`);
+    } catch (e) {
+      log(`[2/2] ${targetAgent}: not configured \u2014 ${e.message}`);
+      log("      You can add the MCP server + hook manually (see the README).");
+    }
+    log(
+      `
+Backthread is set up for ${targetAgent}. New sessions are captured automatically.` + (authed ? "" : " Run `backthread login` to finish authorizing.")
+    );
+    const exitCode2 = !authed && !opts.skipAuth ? 1 : 0;
+    return { exitCode: exitCode2, authed, hookRegistered: agentResult !== null, backfill: null, agentResult };
+  }
   let hookRegistered = false;
   if (opts.skipHook) {
     log("[2/3] Hook: skipped (registered by the plugin manifest).");
   } else {
     try {
-      const { wrote, path } = await registerHook(cwd, deps);
+      const { wrote, path } = await registerHook(deps);
       hookRegistered = true;
       log(
         wrote ? `[2/3] Hook: SessionEnd capture hook added to ${path}.` : `[2/3] Hook: SessionEnd capture hook already present in ${path} (no change).`
@@ -8046,7 +8552,7 @@ async function runInstall(opts = {}, deps = {}) {
   }
   log("\nBackthread is set up. New sessions are captured automatically when they end.");
   const exitCode = !authed && !opts.skipAuth ? 1 : 0;
-  return { exitCode, authed, hookRegistered, backfill };
+  return { exitCode, authed, hookRegistered, backfill, agentResult: null };
 }
 
 // src/onboardingState.ts
@@ -8170,7 +8676,7 @@ function normalizeState(raw) {
 
 // src/firstRun.ts
 function firstRunStatePath(env = process.env) {
-  return join7(configDir(env), "first-run.json");
+  return join9(configDir(env), "first-run.json");
 }
 function parseFirstRunState(raw) {
   try {
@@ -8189,7 +8695,7 @@ function parseFirstRunState(raw) {
 }
 async function readFirstRunState(env = process.env) {
   try {
-    return parseFirstRunState(await readFile4(firstRunStatePath(env), "utf8"));
+    return parseFirstRunState(await readFile7(firstRunStatePath(env), "utf8"));
   } catch {
     return {};
   }
@@ -8199,12 +8705,12 @@ async function updateFirstRunState(patch, env = process.env) {
     const current = await readFirstRunState(env);
     const next = { ...current, ...patch };
     const dir = configDir(env);
-    await mkdir4(dir, { recursive: true, mode: DIR_MODE });
-    await chmod3(dir, DIR_MODE).catch(() => {
+    await mkdir6(dir, { recursive: true, mode: DIR_MODE });
+    await chmod4(dir, DIR_MODE).catch(() => {
     });
     const path = firstRunStatePath(env);
-    await writeFile4(path, JSON.stringify(next) + "\n", { mode: CONFIG_MODE });
-    await chmod3(path, CONFIG_MODE).catch(() => {
+    await writeFile6(path, JSON.stringify(next) + "\n", { mode: CONFIG_MODE });
+    await chmod4(path, CONFIG_MODE).catch(() => {
     });
   } catch {
   }
@@ -8356,7 +8862,7 @@ function readStream(stream) {
 async function runCapture(input, deps = {}) {
   const env = deps.env ?? process.env;
   const log = deps.log ?? ((m) => console.error(m));
-  const doReadFile = deps.readFileImpl ?? ((p) => readFile5(p, "utf8"));
+  const doReadFile = deps.readFileImpl ?? ((p) => readFile8(p, "utf8"));
   const doReadConfig = deps.readConfigImpl ?? readConfig;
   const fireEnsureAuth = deps.ensureAuthImpl ?? ((e) => {
     void ensureAuth({ env: e }).catch(() => {
@@ -8511,8 +9017,8 @@ async function persistDerived(decisions, repo, config2, decidedAt, ctx) {
 
 // src/fromHook.ts
 import { spawn as spawn2 } from "node:child_process";
-import { join as join8 } from "node:path";
-import { readFile as readFile6, writeFile as writeFile5, mkdir as mkdir5, chmod as chmod4 } from "node:fs/promises";
+import { join as join10 } from "node:path";
+import { readFile as readFile9, writeFile as writeFile7, mkdir as mkdir7, chmod as chmod5 } from "node:fs/promises";
 var KNOWN_AGENTS = /* @__PURE__ */ new Set([
   "claude-code",
   "codex",
@@ -8553,7 +9059,7 @@ function normalizeHookInput(payload, _agent) {
   return out;
 }
 function captureStatePath(env = process.env) {
-  return join8(configDir(env), "capture-sessions.json");
+  return join10(configDir(env), "capture-sessions.json");
 }
 var MAX_REMEMBERED2 = 200;
 function parseState2(raw) {
@@ -8569,7 +9075,7 @@ function parseState2(raw) {
 }
 async function readState2(env) {
   try {
-    return parseState2(await readFile6(captureStatePath(env), "utf8"));
+    return parseState2(await readFile9(captureStatePath(env), "utf8"));
   } catch {
     return { captured: [] };
   }
@@ -8577,12 +9083,12 @@ async function readState2(env) {
 async function writeState2(state, env) {
   try {
     const dir = configDir(env);
-    await mkdir5(dir, { recursive: true, mode: DIR_MODE });
-    await chmod4(dir, DIR_MODE).catch(() => {
+    await mkdir7(dir, { recursive: true, mode: DIR_MODE });
+    await chmod5(dir, DIR_MODE).catch(() => {
     });
     const path = captureStatePath(env);
-    await writeFile5(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
-    await chmod4(path, CONFIG_MODE).catch(() => {
+    await writeFile7(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
+    await chmod5(path, CONFIG_MODE).catch(() => {
     });
   } catch {
   }
@@ -8671,6 +9177,15 @@ async function runFromHook(deps = {}) {
       const mark = deps.markCapturedImpl ?? markSessionCaptured;
       await mark(input.session_id, env).catch(() => {
       });
+      if (isTerminallyProcessed(outcome)) {
+        await (deps.markSweepProcessedImpl ?? markSweepProcessed)(input.session_id, env).catch(() => {
+        });
+      }
+    }
+    if (agent === "claude-code") {
+      const sweep = deps.runSweepImpl ?? runGapRecoverySweep;
+      await sweep({ cwd: input.cwd }, { env, captureDeps: deps.captureDeps }).catch(() => {
+      });
     }
     return {
       exitCode: 0,
@@ -32973,7 +33488,9 @@ function formatQueryOutcome(outcome, question) {
 function buildMcpServer(deps = {}) {
   const server = new McpServer({
     name: deps.name ?? "backthread",
-    version: deps.version ?? "0.0.0"
+    // Report the package's real version (read from package.json, ARP-478) instead of a
+    // pinned 0.0.0, so an MCP host's serverInfo shows the installed Backthread version.
+    version: deps.version ?? cliVersion()
   });
   server.registerTool(
     "capture",
@@ -33033,6 +33550,9 @@ Usage:
   backthread mcp                Start the MCP server (capture + query tools) over stdio
   backthread install            Set up capture for this repo (login + hook + backfill history)
                           [--claim <code>] [--skip-auth] [--skip-hook] [--skip-backfill]
+  backthread install --agent <codex|cursor|gemini>
+                          Set up capture for another agent: write its USER-GLOBAL
+                          MCP server config + session-end capture hook (idempotent)
   backthread help               Show this message
 
 Docs: https://app.backthread.dev`;
@@ -33116,8 +33636,15 @@ async function main(argv) {
       return result.exitCode;
     }
     case "install": {
+      const agentFlag = flagValue(rest, "--agent");
+      const agent = parseInstallAgent(agentFlag);
+      if (agentFlag !== void 0 && agent === null) {
+        console.error(`Unknown --agent "${agentFlag}". Use one of: codex, cursor, gemini, claude-code.`);
+        return 1;
+      }
       const result = await runInstall({
         claim: parseClaimFlag(rest),
+        agent: agent ?? void 0,
         skipAuth: rest.includes("--skip-auth"),
         skipHook: rest.includes("--skip-hook"),
         skipBackfill: rest.includes("--skip-backfill")

package/hooks/hooks.json

@@ -1,12 +1,12 @@
 {
-  "$comment": "The SessionEnd capture hook, declared in the PLUGIN MANIFEST (referenced from .claude-plugin/plugin.json). When Backthread is installed as a Claude Code plugin, this registers the hook automatically — no mutation of the user's .claude/settings.json. The command routes through the shared `--from-hook` entrypoint with `--detach`: it reads the SessionEnd payload off stdin, then re-spawns a DETACHED worker that does the slow LOCALLY-redacted redact→infer→persist round-trip and returns immediately — so a ≥30s inference can't be SIGTERM'd by CC's SessionEnd hook timeout (or reaped on session exit). Best-effort, never blocks/delays the session, always exits 0 (ARP-682). `--agent claude-code` selects the CC payload shape. Mirrored by the .claude/settings.json fallback that `backthread install` writes for the bare-npx (non-plugin) path. We register ONLY SessionEnd (once per session) on purpose — `runCapture` also handles a Stop payload, but Stop fires on every turn-end, which would capture far too aggressively, so Stop is intentionally NOT registered here.",
+  "$comment": "The SessionEnd capture hook, declared in the PLUGIN MANIFEST (referenced from .claude-plugin/plugin.json). When Backthread is installed as a Claude Code plugin, this registers the hook automatically AT USER/GLOBAL SCOPE — no mutation of the user's project .claude/settings.json, and it fires across EVERY repo AND git worktree (ARP-680: a per-project, gitignored .claude/settings.json hook is exactly what froze the dogfood log — worktree sessions never carried it; an installed plugin's hooks follow the user, not the cwd). The command invokes the plugin's BUNDLED, self-contained bin via ${CLAUDE_PLUGIN_ROOT} (ARP-474's dist-bundle/backthread.js — committed to git so the marketplace-cloned plugin has it; CC runs no build step on install), NOT `npx backthread`, which would resolve a possibly-stale or absent global / npm-linked install (the second half of the ARP-680 dogfood freeze). The detached worker re-spawns via process.execPath + process.argv[1], so pointing argv[1] at the bundle propagates the same self-contained bin through the WHOLE chain (hook → detached worker). It routes through the shared `--from-hook` entrypoint with `--detach`: it reads the SessionEnd payload off stdin, then re-spawns a DETACHED worker that does the slow LOCALLY-redacted redact→infer→persist round-trip and returns immediately — so a ≥30s inference can't be SIGTERM'd by CC's SessionEnd hook timeout (or reaped on session exit). Best-effort, never blocks/delays the session, always exits 0 (ARP-682). `--agent claude-code` selects the CC payload shape. Mirrored by the USER-SCOPE ~/.claude/settings.json fallback that `backthread install` writes for the bare-npx (non-plugin) path (ARP-503). We register ONLY SessionEnd (once per session) on purpose — `runCapture` also handles a Stop payload, but Stop fires on every turn-end, which would capture far too aggressively, so Stop is intentionally NOT registered here.",
   "hooks": {
     "SessionEnd": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "npx backthread capture --from-hook --agent claude-code --detach"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist-bundle/backthread.js\" capture --from-hook --agent claude-code --detach"
           }
         ]
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "backthread",
-  "version": "0.1.4",
-  "description": "Backthread CLI — capture the why behind your AI-coded changes from your Claude Code sessions, and ask how your codebase works without leaving the terminal. Source code and tool I/O are redacted locally before anything leaves your machine.",
+  "version": "0.2.1",
+  "description": "Backthread helps you understand your codebase while AI ships features. The CLI captures the why behind every AI session and lets you ask how your codebase works, right from the terminal.",
   "license": "MIT",
   "author": "Backthread",
   "homepage": "https://backthread.dev",