backthread 0.1.3 → 0.2.0

package/.claude-plugin/plugin.json

@@ -2,10 +2,16 @@
   "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",
+  "version": "0.2.0",
   "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]";
@@ -7395,6 +7395,19 @@ function isForeignRelativePath(p) {
   const stripped = p.replace(/^(?:\.[\\/])+/, "");
   return /^\.\.(?:[\\/]|$)/.test(stripped);
 }
+function normalizeRepoRelative(rel) {
+  const out = [];
+  for (const seg of rel.split(/[\\/]/)) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (out.length === 0) return null;
+      out.pop();
+      continue;
+    }
+    out.push(seg);
+  }
+  return out.join("/");
+}
 function relativizeUnder(abs, root) {
   const trimmedRoot = root.replace(/\/+$/, "");
   if (trimmedRoot.length === 0) return null;
@@ -7454,10 +7467,12 @@ function sessionPaths(records, repoRoot) {
         if (root === null) continue;
         const rel = relativizeUnder(p, root);
         if (rel === null || rel.length === 0) continue;
-        seen.add(rel);
+        const norm = normalizeRepoRelative(rel);
+        if (norm === null || norm.length === 0) continue;
+        seen.add(norm);
       } else if (!isForeignRelativePath(p)) {
-        const rel = p.replace(/^(?:\.\/)+/, "");
-        if (rel.length > 0) seen.add(rel);
+        const norm = normalizeRepoRelative(p.replace(/^(?:\.\/)+/, ""));
+        if (norm !== null && norm.length > 0) seen.add(norm);
       }
     }
   }
@@ -7702,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";
@@ -7822,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 {
@@ -7833,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 [];
+    }
+  };
+  const baseReadFile = deps.readFileImpl ?? ((p) => readFile4(p, "utf8"));
+  const doReadFile = async (p) => {
+    try {
+      return await baseReadFile(p);
+    } catch {
+      return "";
+    }
+  };
+  const basePathExists = deps.pathExistsImpl ?? defaultPathExists;
+  const doPathExists = async (p) => {
+    try {
+      return await basePathExists(p);
+    } catch {
+      return false;
     }
-    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 doMainRoot = (c) => {
+    try {
+      return (deps.mainRootImpl ?? defaultMainRoot)(c);
+    } catch {
+      return null;
     }
-    log(`  ${file2}: ${outcome.status}${typeof outcome.count === "number" ? ` (${outcome.count})` : ""}`);
+  };
+  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);
+  }
+}
+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;
   }
-  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 };
+  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
@@ -7892,19 +8388,22 @@ var TRUST_COPY = [
   "    code blocks replaced with [code redacted] \u2014 to Backthread's Worker, never source.",
   "  Full details: https://app.backthread.dev/security"
 ].join("\n");
-var HOOK_COMMAND = "npx backthread capture";
-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");
+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(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) {
@@ -7932,27 +8431,49 @@ 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) {
   const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks) ? { ...settings.hooks } : {};
   const sessionEnd = Array.isArray(hooks.SessionEnd) ? [...hooks.SessionEnd] : [];
-  if (sessionEnd.some(groupHasOurCommand)) return null;
-  sessionEnd.push({
-    hooks: [{ type: "command", command: HOOK_COMMAND }]
+  if (sessionEnd.some((g) => groupHasCommand(g, HOOK_COMMAND))) return null;
+  let migrated = false;
+  const nextSessionEnd = sessionEnd.map((group) => {
+    const rewritten = rewriteLegacyCommand(group);
+    if (rewritten !== group) migrated = true;
+    return rewritten;
   });
-  hooks.SessionEnd = sessionEnd;
+  if (!migrated) {
+    nextSessionEnd.push({ hooks: [{ type: "command", command: HOOK_COMMAND }] });
+  }
+  hooks.SessionEnd = nextSessionEnd;
   return { ...settings, hooks };
 }
-function groupHasOurCommand(group) {
+function groupHasCommand(group, command) {
   if (!group || typeof group !== "object") return false;
   const inner = group.hooks;
   if (!Array.isArray(inner)) return false;
   return inner.some(
-    (h) => h && typeof h === "object" && h.command === HOOK_COMMAND
+    (h) => h && typeof h === "object" && h.command === command
   );
 }
+function rewriteLegacyCommand(group) {
+  if (!group || typeof group !== "object") return group;
+  const inner = group.hooks;
+  if (!Array.isArray(inner)) return group;
+  let changed = false;
+  const nextInner = inner.map((h) => {
+    if (!h || typeof h !== "object") return h;
+    const cmd = h.command;
+    if (typeof cmd === "string" && cmd !== HOOK_COMMAND && OUR_HOOK_COMMANDS.has(cmd)) {
+      changed = true;
+      return { ...h, command: HOOK_COMMAND };
+    }
+    return h;
+  });
+  return changed ? { ...group, hooks: nextInner } : group;
+}
 async function runInstall(opts = {}, deps = {}) {
   const env = opts.env ?? process.env;
   const log = opts.log ?? ((m) => console.error(m));
@@ -7977,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).`
@@ -8007,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
@@ -8131,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 {
@@ -8150,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 {};
   }
@@ -8160,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 {
   }
@@ -8317,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(() => {
@@ -8472,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",
@@ -8514,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) {
@@ -8530,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: [] };
   }
@@ -8538,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 {
   }
@@ -8632,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,
@@ -32934,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",
@@ -32994,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`;
@@ -33077,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. `npx backthread capture` reads the SessionEnd payload off stdin, derives this session's decisions LOCALLY-redacted, and persists them best-effort; it always exits 0 so a capture hiccup can never disrupt the session. 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"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist-bundle/backthread.js\" capture --from-hook --agent claude-code --detach"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backthread",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "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.",
   "license": "MIT",
   "author": "Backthread",