backthread 0.2.2 → 0.3.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "backthread",
   "displayName": "Backthread",
   "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.2",
+  "version": "0.3.0",
   "author": {
     "name": "Backthread"
   },

package/README.md

@@ -5,14 +5,27 @@
 
 **Keep the thread on what your AI agent actually shipped.**
 
+```bash
+npx backthread
+```
+
+One command, the whole setup: signs you in (one browser click), connects this
+repo, wires up automatic capture, and hands you the link to your live **"How it
+works"** diagram. Re-run it any time — it's idempotent, so a returning user just
+gets told they're good to go.
+
+> **In Claude Code?** `/plugin marketplace add backthread/backthread` →
+> `/plugin install backthread@backthread` → `/backthread:start`. The plugin
+> bundles the CLI, so there's no separate npm step.
+
 When you hand code to AI agents (Claude Code, Codex, Cursor), you stop reading
 every change — and a few weeks later you own a codebase you never internalized.
-Debugging slows down, refactors get scary.
-
-Backthread captures the **why** behind each change straight from your agent
-sessions, so you can ask *"how does X work?"* and stay oriented without
-spelunking through PRs. The decisions become a live **"How it works"** diagram
-and changelog at [backthread.dev](https://backthread.dev).
+Debugging slows down, refactors get scary. Backthread captures the **why** behind
+each change straight from your agent sessions, so you can ask *"how does X work?"*
+and stay oriented without spelunking through PRs. The decisions become a live
+**"How it works"** diagram and changelog at
+[app.backthread.dev](https://app.backthread.dev) — see the
+[live demo](https://app.backthread.dev/demo).
 
 ## Your source code never leaves your machine
 
@@ -36,11 +49,26 @@ rather say so than paper over it. The redaction fence is open source
 ([`@backthread/redact`](https://www.npmjs.com/package/@backthread/redact)) so you
 can verify it — read more at [backthread.dev/security](https://backthread.dev/security).
 
-## Quick start
+## What `npx backthread` does
 
-### Claude Code → install the plugin (one click, recommended)
+The bare command is the unified front door. Under the hood it:
 
-In Claude Code:
+1. **Signs you in** — opens your browser for one click (you'll need a free
+   [Backthread](https://backthread.dev) account; the CLI never sees a password,
+   and your device token is never printed or copied to the clipboard).
+2. **Wires up capture** — registers a hook so each Claude Code session is
+   captured automatically when it ends.
+3. **Backfills history** — replays your recent Claude Code sessions in this repo
+   so your "How it works" log isn't empty on day one.
+
+Then keep coding. At the end of every Claude Code session, Backthread captures
+the decisions automatically — nothing to remember. Ask *"how does X work?"* right
+inside Claude Code (the `backthread` MCP server exposes a `query` tool), or open
+the live diagram at [app.backthread.dev](https://app.backthread.dev).
+
+### Claude Code plugin (alternative)
+
+Prefer the marketplace? In Claude Code:
 
 ```
 /plugin marketplace add backthread/backthread
@@ -52,30 +80,9 @@ Installing the plugin bundles the CLI — no separate npm step — and registers
 **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`
+just signs you in.
 
-In your project:
-
-```bash
-npx backthread install
-```
-
-That's the whole setup. `install`:
-
-1. **Signs you in** — opens your browser for one click (you'll need a free
-   [Backthread](https://backthread.dev) account; the CLI never sees a password,
-   and your device token is never printed or copied to the clipboard).
-2. **Wires up capture** — registers a hook so each Claude Code session is
-   captured automatically when it ends.
-3. **Backfills history** — replays your recent Claude Code sessions in this repo
-   so your "How it works" log isn't empty on day one.
-
-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>`
+### Codex / Cursor / Gemini CLI
 
 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**
@@ -92,18 +99,11 @@ clobbers your other config). Then `npx backthread login` once to authorize. Gemi
 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.
-2. **Keep coding** — at the end of every Claude Code session, Backthread captures
-   the decisions automatically. Nothing to remember.
-3. **Ask "how does X work?"** — query your decision log right inside Claude Code
-   (the `backthread` MCP server exposes a `query` tool), or open the live diagram
-   at [app.backthread.dev](https://app.backthread.dev).
-
 ## Commands
 
 ```
+backthread           Set up Backthread — the unified front door (sign in + connect + capture).
+                     Idempotent: a returning user is told they're good to go.
 backthread install   Set up capture for this repo (sign in + hook + backfill)
 backthread start     First-run for the Claude Code plugin (sign in + your next step)
 backthread login     Authorize this device (opens your browser)
@@ -119,7 +119,8 @@ backthread help      Show usage
 
 ## Learn more
 
-- **Live app** — [backthread.dev](https://backthread.dev)
+- **Live app & demo** — [app.backthread.dev](https://app.backthread.dev) · [app.backthread.dev/demo](https://app.backthread.dev/demo)
+- **Marketing site** — [backthread.dev](https://backthread.dev)
 - **How your data is handled** — [backthread.dev/security](https://backthread.dev/security)
 - **Source & internals** — [github.com/backthread/backthread](https://github.com/backthread/backthread)
 

package/dist-bundle/backthread.js

@@ -6885,6 +6885,10 @@ var require_dist = __commonJS({
   }
 });
 
+// src/bin/backthread.ts
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { realpathSync } from "node:fs";
+
 // src/login.ts
 import { hostname } from "node:os";
 
@@ -7516,6 +7520,27 @@ function resolveRepo(cwd, readRemote = defaultRemoteReader) {
   const remote = readRemote(cwd);
   return remote ? parseRepoFromRemote(remote) : null;
 }
+var defaultGitRunner = (cwd, args) => {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return null;
+  }
+};
+function resolveGitContext(cwd, run = defaultGitRunner) {
+  const rawBranch = run(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const branch = rawBranch ? rawBranch.trim() : "";
+  const rawSha = run(cwd, ["rev-parse", "HEAD"]);
+  const sha = rawSha ? rawSha.trim() : "";
+  return {
+    branch: branch && branch !== "HEAD" ? branch : null,
+    headSha: sha || null
+  };
+}
 
 // src/infer.ts
 async function localByokInfer(_transcript, _config, _opts) {
@@ -7558,6 +7583,9 @@ async function serverInfer(transcript, config2, opts = {}) {
     body.repo = { owner: opts.repo.owner, name: opts.repo.name };
     if (opts.decidedAt) body.decidedAt = opts.decidedAt;
     if (opts.filePaths && opts.filePaths.length > 0) body.filePaths = opts.filePaths;
+    if (opts.captured?.branch != null) body.capturedBranch = opts.captured.branch;
+    if (opts.captured?.headSha != null) body.capturedHeadSha = opts.captured.headSha;
+    if (opts.captured?.at != null) body.capturedAt = opts.captured.at;
   }
   let res;
   try {
@@ -8555,6 +8583,33 @@ Backthread is set up for ${targetAgent}. New sessions are captured automatically
   return { exitCode, authed, hookRegistered, backfill, agentResult: null };
 }
 
+// src/entry.ts
+var PLUGIN_MARKETPLACE = "backthread/backthread";
+var PLUGIN_INSTALL = "backthread@backthread";
+function detectEntry(input = {}) {
+  if (input.claim && input.claim.trim().length > 0) return "web";
+  return "terminal";
+}
+function isInsideClaudeCode(env = process.env) {
+  return env.CLAUDECODE === "1";
+}
+function captureGuidance(env = process.env) {
+  if (isInsideClaudeCode(env)) {
+    return [
+      `Capture (the "why"): you're in Claude Code \u2014 install the plugin so every`,
+      "  session is captured automatically (it wires the hook + MCP across all your",
+      "  repos and worktrees):",
+      `    /plugin marketplace add ${PLUGIN_MARKETPLACE}`,
+      `    /plugin install ${PLUGIN_INSTALL}`
+    ].join("\n");
+  }
+  return [
+    'Capture (the "why"): run `npx backthread install` here to wire the capture hook',
+    "  so each Claude Code session is captured automatically when it ends.",
+    "  Using Codex / Cursor / Gemini? `npx backthread install --agent <codex|cursor|gemini>`."
+  ].join("\n");
+}
+
 // src/onboardingState.ts
 function parseSlug(slug) {
   const parts = slug.trim().replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
@@ -8734,6 +8789,7 @@ async function runStart(opts = {}, deps = {}) {
   const env = opts.env ?? process.env;
   const log = opts.log ?? ((m) => console.error(m));
   const cwd = opts.cwd ?? process.cwd();
+  const entry = opts.entry ?? detectEntry({ claim: opts.claim, env });
   const readState3 = deps.readStateImpl ?? readFirstRunState;
   const existingState = await readState3(env).catch(() => ({}));
   if (existingState.onboarded === true) {
@@ -8742,6 +8798,10 @@ async function runStart(opts = {}, deps = {}) {
     if (cfg.device_token) {
       log("Backthread is already set up on this machine \u2014 you're good to go.");
       log("  New sessions are captured automatically when they end.");
+      const repo = resolveOnboardingRepo({ cwd }, cfg, deps.onboardingDeps?.readRemoteImpl);
+      if (repo) {
+        log(`  View your "How it works" diagram: ${buildRepoDeepLink(repo.owner, repo.name, env)}`);
+      }
       log("  Run `/backthread:capture` to capture the current session now.");
       return { exitCode: 0, status: "already-onboarded", authed: true };
     }
@@ -8772,6 +8832,9 @@ async function runStart(opts = {}, deps = {}) {
     log("      Run `/backthread:start` again to retry authorizing this device.");
     return { exitCode: 1, status: "auth-failed", authed: false };
   }
+  if (entry === "terminal") {
+    log("\n" + captureGuidance(env));
+  }
   const fetchState = deps.fetchStateImpl ?? fetchOnboardingState;
   const stateOut = await fetchState({ cwd }, { env, ...deps.onboardingDeps }).catch(
     () => ({ status: "error", detail: "state fetch failed (swallowed)" })
@@ -8894,24 +8957,31 @@ async function runCapture(input, deps = {}) {
     const decidedAt = sessionTimestamp(records) ?? void 0;
     const filePaths = sessionPaths(records, input.cwd);
     const sessionId = redacted.sessionId ?? input.session_id ?? null;
-    if (redacted.turns.length === 0) {
+    const turnCount = redacted.turns.length;
+    const fromTurn = deps.fromTurnIndex ?? 0;
+    const newTurns = fromTurn > 0 ? redacted.turns.slice(fromTurn) : redacted.turns;
+    if (newTurns.length === 0) {
       return {
         status: "nothing-to-capture",
-        detail: "redaction left no natural-language turns (session was all code / tool I/O).",
-        count: 0
+        detail: turnCount === 0 ? "redaction left no natural-language turns (session was all code / tool I/O)." : `no new turns since the last capture (watermark ${fromTurn} of ${turnCount}).`,
+        count: 0,
+        turnCount
       };
     }
     const transcript = {
       sessionId,
-      turns: redacted.turns,
+      turns: newTurns,
       stats: redacted.stats
     };
     const repo = input.cwd ? resolveRepo(input.cwd, deps.readRemoteImpl) : null;
+    const gitContext = input.cwd ? resolveGitContext(input.cwd, deps.readGitImpl) : { branch: null, headSha: null };
+    const captured = { branch: gitContext.branch, headSha: gitContext.headSha, at: decidedAt ?? null };
     const result = await inferDecisions(transcript, config2, {
       env,
       fetchImpl: deps.fetchImpl,
       decidedAt,
       filePaths,
+      captured,
       ...repo ? { persist: true, repo } : {}
     });
     if (!result.ok) {
@@ -8924,33 +8994,39 @@ async function runCapture(input, deps = {}) {
         status: "persisted-by-server",
         detail: `inference router persisted ${result.decisions.length} decision(s) server-side.`,
         count: result.decisions.length,
-        repoConnected: true
+        repoConnected: true,
+        turnCount
       };
     }
     if (result.decisions.length === 0) {
       return {
         status: "nothing-to-capture",
         detail: "inference returned no decisions for this session.",
-        count: 0
+        count: 0,
+        turnCount
       };
     }
     if (!repo) {
       return {
         status: "nothing-to-capture",
         detail: "derived decisions but could not resolve a repo from cwd (no git remote) \u2014 nothing to claim them under; skipped.",
-        count: 0
+        count: 0,
+        turnCount
       };
     }
-    return persistDerived(result.decisions, repo, config2, decidedAt, {
+    const out = await persistDerived(result.decisions, repo, config2, decidedAt, {
       env,
       fetchImpl: deps.fetchImpl,
       log,
       // Carry the session id so the connect-nudge can throttle once-per-session
       // — the SessionEnd hook fires once, but manual/MCP captures fire many times.
       sessionId,
+      // ARP-696 — the session's git context, for the held-state decision server-side.
+      captured,
       // first-capture confirmation seam (threaded so tests can stub it).
       firstCaptureConfirmImpl: deps.firstCaptureConfirmImpl
     });
+    return { ...out, turnCount };
   } catch (e) {
     return { status: "error", detail: `capture failed (swallowed): ${e.message}` };
   }
@@ -8963,6 +9039,13 @@ async function persistDerived(decisions, repo, config2, decidedAt, ctx) {
   }
   const body = {
     repo: { owner: repo.owner, name: repo.name },
+    // ARP-696 — session-level git context (the ingest-decisions validator reads it
+    // body-level and stamps each decision). Each field only when present; absent →
+    // the server keeps the decision merged (back-compat). It's the repo-less /
+    // self-persist path, so a held decision waits for the repo to connect + reconcile.
+    ...ctx.captured?.branch != null ? { capturedBranch: ctx.captured.branch } : {},
+    ...ctx.captured?.headSha != null ? { capturedHeadSha: ctx.captured.headSha } : {},
+    ...ctx.captured?.at != null ? { capturedAt: ctx.captured.at } : {},
     decisions: decisions.map((d) => ({
       ...d,
       ...decidedAt && d.decidedAt === void 0 ? { decidedAt } : {}
@@ -9065,19 +9148,26 @@ var MAX_REMEMBERED2 = 200;
 function parseState2(raw) {
   try {
     const obj = JSON.parse(raw);
-    if (obj && typeof obj === "object" && Array.isArray(obj.captured)) {
-      const captured = obj.captured.filter((s) => typeof s === "string");
-      return { captured };
+    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+      const o = obj;
+      const captured = Array.isArray(o.captured) ? o.captured.filter((s) => typeof s === "string") : [];
+      const watermarks = {};
+      if (o.watermarks && typeof o.watermarks === "object" && !Array.isArray(o.watermarks)) {
+        for (const [k, v] of Object.entries(o.watermarks)) {
+          if (typeof v === "number" && Number.isFinite(v) && v >= 0) watermarks[k] = v;
+        }
+      }
+      return { captured, watermarks };
     }
   } catch {
   }
-  return { captured: [] };
+  return { captured: [], watermarks: {} };
 }
 async function readState2(env) {
   try {
     return parseState2(await readFile9(captureStatePath(env), "utf8"));
   } catch {
-    return { captured: [] };
+    return { captured: [], watermarks: {} };
   }
 }
 async function writeState2(state, env) {
@@ -9104,7 +9194,27 @@ async function markSessionCaptured(sessionId, env = process.env) {
   if (state.captured.includes(sessionId)) return;
   const captured = [...state.captured, sessionId];
   if (captured.length > MAX_REMEMBERED2) captured.splice(0, captured.length - MAX_REMEMBERED2);
-  await writeState2({ captured }, env);
+  const { [sessionId]: _dropped, ...watermarks } = state.watermarks;
+  await writeState2({ captured, watermarks }, env);
+}
+async function captureWatermark(sessionId, env = process.env) {
+  if (!sessionId || sessionId.trim().length === 0) return 0;
+  const state = await readState2(env);
+  return state.watermarks[sessionId] ?? 0;
+}
+async function setCaptureWatermark(sessionId, turnCount, env = process.env) {
+  if (!sessionId || sessionId.trim().length === 0) return;
+  if (typeof turnCount !== "number" || !Number.isFinite(turnCount) || turnCount < 0) return;
+  const state = await readState2(env);
+  const prev = state.watermarks[sessionId] ?? 0;
+  if (turnCount <= prev) return;
+  const { [sessionId]: _old, ...rest } = state.watermarks;
+  const watermarks = { ...rest, [sessionId]: turnCount };
+  const keys = Object.keys(watermarks);
+  if (keys.length > MAX_REMEMBERED2) {
+    for (const k of keys.slice(0, keys.length - MAX_REMEMBERED2)) delete watermarks[k];
+  }
+  await writeState2({ captured: state.captured, watermarks }, env);
 }
 function spawnDetached(rawPayload, agent, deps = {}) {
   const doSpawn = deps.spawnImpl ?? spawn2;
@@ -9171,12 +9281,22 @@ async function runFromHook(deps = {}) {
         stdout: codexStdout(agent, "duplicate-session")
       };
     }
+    const readWatermark = deps.watermarkImpl ?? captureWatermark;
+    const fromTurnIndex = await readWatermark(input.session_id, env).catch(() => 0);
     const run = deps.runCaptureImpl ?? runCapture;
-    const outcome = await run(input, deps.captureDeps);
+    const outcome = await run(input, { ...deps.captureDeps, fromTurnIndex });
     if (!isTransient(outcome)) {
-      const mark = deps.markCapturedImpl ?? markSessionCaptured;
-      await mark(input.session_id, env).catch(() => {
-      });
+      if (outcome.status === "no-auth") {
+        await (deps.markCapturedImpl ?? markSessionCaptured)(input.session_id, env).catch(() => {
+        });
+      } else if (typeof outcome.turnCount === "number") {
+        await (deps.setWatermarkImpl ?? setCaptureWatermark)(
+          input.session_id,
+          outcome.turnCount,
+          env
+        ).catch(() => {
+        });
+      }
       if (isTerminallyProcessed(outcome)) {
         await (deps.markSweepProcessedImpl ?? markSweepProcessed)(input.session_id, env).catch(() => {
         });
@@ -33531,6 +33651,9 @@ async function startMcpServer(deps = {}) {
 var USAGE = `backthread \u2014 capture the "why" of your AI-coded changes
 
 Usage:
+  backthread                    Set up Backthread (the unified front door \u2014 same as
+                          \`backthread start\`): trust copy + one-tap auth + your next
+                          step. Idempotent. [--claim <code>]
   backthread start              First-run setup (backs the /backthread:start slash command):
                           trust copy + one-tap auth + your next step. Idempotent.
                           [--claim <code>]
@@ -33574,8 +33697,18 @@ function flagValue(rest, flag) {
   if (!value || value.startsWith("--")) return void 0;
   return value;
 }
-async function main(argv) {
+async function runOnboarding(rest) {
+  const claim = parseClaimFlag(rest);
+  const result = await runStart({
+    claim,
+    device: rest.includes("--device"),
+    entry: detectEntry({ claim })
+  });
+  return result.exitCode;
+}
+async function main(argv, deps = {}) {
   const [command, ...rest] = argv;
+  const onboarding = deps.runOnboardingImpl ?? runOnboarding;
   switch (command) {
     case "login": {
       const device = rest.includes("--device");
@@ -33629,11 +33762,7 @@ async function main(argv) {
       return null;
     }
     case "start": {
-      const result = await runStart({
-        claim: parseClaimFlag(rest),
-        device: rest.includes("--device")
-      });
-      return result.exitCode;
+      return onboarding(rest);
     }
     case "install": {
       const agentFlag = flagValue(rest, "--agent");
@@ -33651,23 +33780,48 @@ async function main(argv) {
       });
       return result.exitCode;
     }
+    case void 0:
+      return onboarding(rest);
     case "help":
     case "--help":
     case "-h":
-    case void 0:
       console.log(USAGE);
       return 0;
     default:
+      if (command.startsWith("-")) return onboarding(argv);
       console.error(`Unknown command: ${command}
 
 ${USAGE}`);
       return 1;
   }
 }
-main(process.argv.slice(2)).then((code) => {
-  if (code === null) return;
-  process.exit(code);
-}).catch((err) => {
-  console.error(`backthread: ${err.message ?? err}`);
-  process.exit(1);
-});
+function isEntryPoint() {
+  try {
+    const entry = process.argv[1];
+    if (!entry) return false;
+    const self = fileURLToPath2(import.meta.url);
+    const resolve = (p) => {
+      try {
+        return realpathSync(p);
+      } catch {
+        return p;
+      }
+    };
+    return resolve(self) === resolve(entry);
+  } catch {
+    return true;
+  }
+}
+if (isEntryPoint()) {
+  main(process.argv.slice(2)).then((code) => {
+    if (code === null) return;
+    process.exit(code);
+  }).catch((err) => {
+    console.error(`backthread: ${err.message ?? err}`);
+    process.exit(1);
+  });
+}
+export {
+  main,
+  runOnboarding
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backthread",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "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",