npm - backthread - Versions diffs - 0.1.0 → 0.1.2 - Mend

backthread 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,431 +1,93 @@
-# backthread — CLI / plugin
+# backthread
-The local **agent plugin** spine for Backthread's live capture loop + in-Claude-Code
-query (F7). This package is the shared entrypoint the later F7 surfaces hang off:
-the `SessionEnd`/`Stop` capture hook (F7.2), the `/backthread capture` slash command
-(F7.3), and the MCP server (F7.4) all call into it.
+[![npm](https://img.shields.io/npm/v/backthread?logo=npm)](https://www.npmjs.com/package/backthread)
+[![license](https://img.shields.io/npm/l/backthread?label=license)](./LICENSE)
-It is a **separate npm package** from the diagram app (mirrors `worker/`): it
-does **not** modify the root `package.json` and has no app dependencies. Its only
-runtime dependency is the official MCP SDK (`@modelcontextprotocol/sdk`), pulled
-in by the F7.4 `backthread mcp` server; everything else uses Node builtins, so `npx backthread` stays a small, audit-light download.
+**Keep the thread on what your AI agent actually shipped.**
-## Status (F7.1 / ARP-432, F7.2 / ARP-433, F7.3 / ARP-434, F7.4 / ARP-435, F7.7 / ARP-438)
+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.
-Scaffold + `backthread login` (the browser OAuth-loopback device-token client), the
-`backthread capture` SessionEnd/Stop hook handler (F7.2), the `/backthread:capture` MANUAL
-slash command (F7.3), the `backthread mcp` server (F7.4) exposing the in-Claude-Code
-`capture` + `query` tools, and `backthread install` (F7.7) — the onboarding glue that
-authorizes the device, registers the SessionEnd hook, and backfills history.
+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).
-## Commands
-```
-backthread start            First-run setup: trust copy + one-tap auth + your next step (backs /backthread:start)
-backthread login            Authorize this device (opens your browser)
-backthread login --device   Headless / SSH login (device-code flow — STUBBED, see below)
-backthread whoami           Show the current device's config (token is never printed)
-backthread capture          Capture this session's decisions (run by the SessionEnd/Stop hook)
-backthread capture --manual Manually capture a session now (backs the /backthread:capture slash command)
-backthread mcp              Start the MCP server (capture + query tools) over stdio
-backthread install          Set up capture for this repo: login + register hook + backfill history
-backthread help             Usage
-```
-## `backthread login` — the loopback flow
-1. Starts a localhost server on `http://127.0.0.1:<random-port>/callback`.
-2. Opens the browser to `app.backthread.dev/cli-auth?port=<port>&state=<nonce>`.
-3. You click **Authorize** (you're already signed into the web app). The page
-   mints a capture-scoped `backthread_pat_…` device token via the `mint-device-token`
-   Edge Function (F7.0 / ARP-448) and redirects back to the loopback with the
-   token + the same `state` nonce.
-4. The CLI validates the `state` nonce (CSRF guard) and writes the token to
-   `~/.backthread/config.json` at **chmod `0600`**.
-One browser click, zero copy-paste. **The token never touches the clipboard or
-terminal scrollback** — it goes straight from the loopback query string into the
-0600 config file and is never printed or logged.
-## Inference router — `infer.ts` (F7.IR / ARP-450)
-`inferDecisions(transcript, config, opts)` decides **how** decisions get derived
-from a normalized + redacted transcript and **whose** credentials pay, then
-returns the derived decisions for the caller (F7.2 hook / F7.4 MCP) to POST to
-`ingest-decisions` — **unless** the result says the server already persisted them.
-- **Model 2 (server-side, our keys) — the DEFAULT.** POSTs the redacted
-  transcript to the Worker's F7.SF `POST /infer-decisions` (auth: the F7.0
-  `backthread_pat_` device token), which runs the tuned Gemini-bulk → Sonnet-tiebreak
-  pipeline with our keys. Pass `persist: true` + `repo` to have the server also
-  write the decisions (membership-gated) — then `result.persisted` is `true` and
-  the caller MUST NOT re-POST to `ingest-decisions` (double-write). Default is
-  derive-only: the caller persists.
-- **Model 3 (BYO API key) — a power-user override, SEAM ONLY.** `localByokInfer`
-  is a stub marked `// TODO(F7.19 / ARP-463)` that always reports "no BYOK
-  configured", so the router falls through to Model 2. Local BYOK execution +
-  key storage/validation/settings UX ships in F7.18/19 (ARP-462/463).
-- **Model 4 — parked, not modelled here** (post-MVP, opt-in; ToS-blocked variants
-  are off the table per the F7.IV spike, ARP-449).
-**Trust boundary (be honest — Model 2 is the weaker claim).** Because the
-default path runs inference on our servers, the thing that leaves your machine
-on Model 2 is **the redacted transcript** — natural-language prose only. The
-plugin redacts LOCALLY first (drops every tool-use / tool-result record and
-redacts fenced code to `[code redacted]`), so **no source code and no tool I/O
-ever leave the machine**; the Worker re-runs the fenced-code scrub server-side
-as a fail-closed backstop against a plugin redaction bug, derives the decisions,
-and **discards the transcript right after extraction — processed in memory,
-never stored.** That is a *weaker* claim than the BYOK/Model-3 path, where
-nothing but the derived decisions ever leaves the machine — and we say so out
-loud rather than paper over it. (Model 3 is still a SEAM only; until F7.19/20
-ship, every run takes the Model-2 server path.) This is distinct from the
-hosted **repo-ingestion** pipeline (the diagram), which clones your code into a
-destroy-on-exit sandbox and never stores source either — two separate paths,
-same never-store-source posture for actual code. The canonical statement
-lives at [`/security`](https://backthread.dev/security).
-Dependency-free (global `fetch`); a `fetchImpl` seam lets tests run without a
-network or Worker. Worker origin is overridable via `BACKTHREAD_WORKER_URL`
-(e.g. `http://localhost:8787` for `wrangler dev`).
-## `backthread capture` — the SessionEnd/Stop hook (F7.2 / ARP-433)
-The self-maintaining moat: at the end of every agent session, derive the
-session's **decisions** (the "why") and land them in the hosted log, so it stays
-current after the one-time F5 backfill. `backthread capture` is the headless hook
-handler. Pipeline (all LOCAL until the last network hop):
-1. Read the hook input (JSON on **stdin**; `transcript_path` + `cwd` +
-   `session_id`). A `BACKTHREAD_HOOK_INPUT` env var is accepted as a dev/test fallback.
-2. Read the `.jsonl` transcript off disk.
-3. **Redact LOCALLY** (`redact.ts` — the security fence): drop every
-   tool-use / tool-result record, keep only natural-language prose, redact fenced
-   code blocks to `[code redacted]`. **No source code or tool I/O ever leaves the
-   machine.**
-4. Derive decisions via the **F7.IR router** (`inferDecisions`). When a repo
-   resolves from `cwd`, we pass `persist: true` so the server (membership-gated)
-   also writes them — then `result.persisted` is `true`.
-5. Persist:
-   - `result.persisted` → **done** (re-POSTing would double-write).
-   - else POST the **derived** decisions to `ingest-decisions`, which routes
-     connected vs **repo-less** (F7.8) server-side.
-**Best-effort + non-blocking (the load-bearing contract):** `runCapture` never
-throws — every failure mode resolves a structured outcome — and `backthread capture`
-**always exits 0**. A capture hiccup can never disrupt or delay the user's Claude
-Code session. If there's no device token, it kicks off `backthread login`
-fire-and-forget (never awaited) and **skips this capture** — the next session
-captures once a token exists.
-### Registering the hook — TWO mechanisms (F7.7 / ARP-438)
-Claude Code runs `SessionEnd` hooks, passing the session JSON on the hook
-process's **stdin**. `npx backthread capture` reads that payload, derives the session's
-decisions (locally-redacted), and persists them best-effort — always exiting 0, so
-the hook host never blocks on it and never sees a non-zero exit. There are two ways
-the hook gets registered, and Backthread uses both depending on how it was installed:
-1. **PRIMARY — the plugin manifest.** When Backthread is installed as a Claude Code
-   plugin, the hook is declared in **`hooks/hooks.json`** (referenced by the
-   `hooks` field of `.claude-plugin/plugin.json`) and Claude Code registers it
-   **automatically on install** — the user's `.claude/settings.json` is never
-   touched. This is the right home: the hook ships + versions with the plugin and
-   is removed cleanly on uninstall. (Schema confirmed against the current Claude
-   Code plugin docs: `hooks/hooks.json`, `command` type.)
-2. **FALLBACK — `backthread install` writes `.claude/settings.json`.** For the bare
-   `npx backthread` (non-plugin) path there is no manifest doing the wiring, so
-   `backthread install` merges this entry into the project's `.claude/settings.json`
-   itself (idempotent — re-running never duplicates it; a strict merge that never
-   clobbers other settings/hooks):
-   ```jsonc
-   {
-     "hooks": {
-       "SessionEnd": [
-         { "hooks": [ { "type": "command", "command": "npx backthread capture" } ] }
-       ]
-     }
-   }
-   ```
-## `backthread start` — the plugin first-run (8B.5 / ARP-486)
-The **in-agent** first-run for the plugin half of the both-equal front door (ARP-482),
-behind the **`/backthread:start`** slash command. Where `backthread install` wires the
-bare-`npx` (non-plugin) path (hook registration + backfill), `start` is the experience
-a founder gets after a **marketplace 1-click** install — the SessionEnd hook is already
-armed by the manifest, so `start` only does the *human* part:
-1. **Idempotence gate.** Reads `~/.backthread/first-run.json`. A returning user
-   (`onboarded` flag set) is **never re-onboarded** — it just confirms they're set up.
-2. **Trust gate.** Prints the **never-store-source** trust copy (the `TRUST_COPY` from
-   `install.ts`, consistent with [`/security`](https://backthread.dev/security)) **before
-   anything else** — the AC requires the claim to precede any transcript processing.
-3. **One-tap auth.** `--claim <code>` (8B.9) exchanges a web-app-minted claim code for a
-   device token — no browser, the web-initiated door. With no claim code it runs the
-   browser **loopback** (`ensureAuth`); an already-authed device short-circuits.
-   `--device` (headless device-code, F7.23) is **out of scope** (→ ARP-467) and is
-   **refused with the loud stub** rather than silently falling back to the loopback
-   (which would hang a headless box).
-4. **State-driven next step.** Reads the **unified onboarding state** (`fetchOnboardingState`,
-   8B.6 — the SAME backend signal the web wizard reads) and renders its canonical next
-   step. When the repo isn't connected this IS the **F7.10 connect nudge** copy
-   (server-driven); a terminal state renders cleanly with the diagram deep-link.
-5. **Mark onboarded.** Persists the flag so step 1 short-circuits next time.
-Exits non-zero **only** on a genuine auth failure (capture won't run until you act);
-the auth failure does **not** mark onboarded, so re-running retries.
-**"Onboarded" is an explicit flag**, not the derived "token present + ≥1 capture": the
-trust gate must precede the very first capture (so we can't key onboarding off having
-already captured), and a token rotation must not re-trigger the wizard. The derived
-onboarding *state* still drives the *next-step* copy — it's just not the onboarding gate.
-### The two confirmation surfaces in the capture path
+## Your source code never leaves your machine
-Two 8B.5 lines live in the capture path itself (not in `start`), each once-per-install:
+Backthread reads your agent **transcripts**, not your repo. Before anything is
+sent, the CLI redacts every transcript **locally**:
-- **Trust gate on the silent hook path** (`maybeShowTrustGate`): the manifest-armed
-  SessionEnd hook can fire **before** any `start`/`install` ran, and `runCapture`'s
-  no-auth path fire-and-forgets `ensureAuth` (which can open a browser). So `runCapture`
-  prints the trust copy **once, before reading the transcript or firing login** — the
-  never-store-source claim holds on both entrypoints. Best-effort + never-throws +
-  never-blocks: it can't break the always-exit-0 capture contract.
-- **First-capture confirmation** (`maybeFirstCaptureConfirm`): after the **first** capture
-  that lands decisions against a **connected** repo, a once-only **"captured N — view them
-  in your "How it works" diagram: <deep-link>"** line. Mutually exclusive with the connect
-  nudge (which owns the not-connected case). Throttled via `firstCaptureShown` in the
-  same `first-run.json`. Best-effort.
+- **Drops** every tool call and tool result — where source code and command output live.
+- **Keeps** only natural-language prompts and the agent's reasoning.
+- **Redacts** any fenced code block to `[code redacted]`.
-## `backthread install` — onboarding (F7.7 / ARP-438)
+So no source code and no tool I/O ever leave your machine. Because the default
+path runs inference on our servers, what *does* leave is the **redacted
+transcript** — natural-language prose only. The Worker re-runs the fenced-code
+scrub server-side as a fail-closed backstop, derives the **decisions**, and
+discards the transcript right after — processed in memory, never stored. Only
+the decisions are persisted.
-The one-motion first-run that lands capture in the rescue-mode aha moment. It runs
-three steps, reporting each, and exits non-zero **only** on a genuine auth failure
-(the hook + backfill legs are best-effort and never fail the install):
+That's a weaker claim than the bring-your-own-key path — where nothing but the
+derived decisions ever leaves your machine — which is designed and coming. We'd
+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).
-1. **Auth handshake** — reuses `backthread login` via `ensureAuth` (F7.1): if a device
-   token already exists it's reused; otherwise the browser OAuth-loopback runs once.
-2. **Register the SessionEnd hook** — writes the `.claude/settings.json` fallback
-   above (skip with `--skip-hook` when installed as a plugin, where the manifest
-   already registers it).
-3. **Chain the backfill** — runs `backthread`'s **cli-native backfill** (below) so the
-   decision log is **non-empty at the aha moment**, then self-maintaining via the
-   live hook. Best-effort; skipped automatically when not yet authorized.
+## Quick start
-Flags: `--skip-auth`, `--skip-hook`, `--skip-backfill`.
+In your project:
-Before any transcript is read, `backthread install` prints the **never-store-source**
-trust copy (consistent with [`/security`](https://backthread.dev/security)):
-redaction happens locally; source code + tool I/O never leave the machine; only
-the **derived decisions** are stored. On the default server-inference path a
-*redacted, natural-language-only* transcript does leave the machine — never
-source, never tool output — and it's **discarded right after extraction, never
-stored** (the server re-redacts as a fail-closed backstop). The copy states this
-weaker claim plainly rather than hiding it behind "only decisions leave."
-### Cli-native backfill — `backfill.ts` (the architecture decision, FLAGGED)
-The original F5 backfill is `scripts/ingest/decisions/backfill-cli.ts`, but the
-`npx backthread` plugin **cannot ship `scripts/`** (separate dependency-light bundle,
-`rootDir: src`). So `backthread install` chains a **cli-native** backfill instead: it
-enumerates this repo's existing Claude Code transcripts at
-`~/.claude/projects/<encoded-cwd>/*.jsonl` (the layout F7.3 established) and runs
-each one through the **same `runCapture` pipeline** as the live hook. It does not
-reimplement the redact/derive/persist fence — the never-store-source posture is
-inherited verbatim. It is sequential (a one-shot seed has no latency budget),
-best-effort (a missing dir / unreadable file / per-transcript failure is tallied,
-never fatal), and idempotent (the pipeline's dedupe key makes re-running safe).
-> **SCOPE (flagged):** this cli-native backfill is **Claude-Code-only**. Claude
-> Code's per-repo transcript layout is enumerable with zero dependencies; the
-> **multi-agent** backfill (Codex / Cursor / Gemini CLI via the F7.26 provider
-> registry) stays the **dogfood / server path** in `scripts/`, whose adapters the
-> plugin must not depend on. A founder using other agents still gets *live* capture
-> for them via the per-agent surfaces; only the one-shot history seed is
-> Claude-Code-only here. A shared backfill layer is a follow-up.
-## `/backthread:capture` — the manual slash command (F7.3 / ARP-434)
-The explicit/manual counterpart to the automatic SessionEnd hook: the founder who
-wants to capture **mid-session** ("capture what we just decided, now") or re-run a
-session runs it. It drives the **same `runCapture` pipeline** as F7.2 (local-redact
-→ F7.IR router-derive → hosted-POST) — the redact fence is never reimplemented —
-but differs from the hook in two ways:
-1. **It resolves the transcript itself.** The hook is fed `transcript_path` on
-   STDIN by Claude Code; a slash command is **not** (Claude Code exposes
-   `${CLAUDE_SESSION_ID}` and the cwd to a command, but not the transcript path).
-   So the manual path derives it from Claude Code's on-disk layout:
-   `~/.claude/projects/<slugified-cwd>/<session_id>.jsonl` (the slug replaces every
-   non-alphanumeric char in the absolute cwd with `-`). An explicit
-   `--transcript <path>` always wins. If neither resolves a readable file, it
-   prints an **actionable hint** (run with `--transcript <path>`) — never a silent
-   no-op, and never a browser pop.
-2. **It surfaces a per-run summary to STDOUT** (status + decision count +
-   repo-connected state) and exits non-zero on a genuine failure or when not logged
-   in — the manual analogue of the local pipeline's `summarize()`. (The hook stays
-   silent-to-stderr and always exits 0.) A missing device token surfaces as a
-   `run backthread login` hint; manual mode injects a **no-op `ensureAuth`** so — unlike
-   the best-effort hook — it never kicks off a background browser login.
-### The slash-command mechanism (FLAGGED design choice)
-Claude Code custom commands are merged into **skills**: a file at
-`<plugin>/commands/capture.md` in a plugin named `backthread` becomes **`/backthread:capture`**
-(plugin-namespaced — the faithful realization of the ticket's `/backthread capture`). The
-command file uses Claude Code's **`!`shell injection`**` to run
-`npx backthread capture --manual --session "${CLAUDE_SESSION_ID}" --cwd "$(pwd)"` at
-render time; the bin's summary is inlined into the prompt and the agent relays it.
-This package therefore ships a minimal plugin manifest (`.claude-plugin/plugin.json`)
-+ the command file (`commands/capture.md`), in addition to the `backthread` bin. Both are
-in package.json `files` so they ship via npm. The same files load standalone for
-local dev with `claude --plugin-dir ./cli`. (The hook + MCP-server wiring into a
-user's settings is install-time automation owned by F7.7 / ARP-438, sequenced after
-this task; the command file is the slash-command half.)
-## `backthread mcp` — the MCP server (F7.4 / ARP-435)
-The in-Claude-Code surface for both halves of HMW #2 ("CC = capture/queries
-entry"). `backthread mcp` starts a long-running MCP server over **stdio** (stdout is the
-JSON-RPC channel; all diagnostics go to stderr) exposing two tools:
-- **`capture`** — capture the current/given session's DECISIONS (the "why"). It
-  reuses the **F7.2 `runCapture` pipeline verbatim** (local-redact → derive →
-  hosted-POST) — the redact fence is never reimplemented. Best-effort: a hiccup
-  never disrupts the session. Args: `transcript_path` (**required** — unlike the
-  hook, the MCP tool has no STDIN, so the host must supply the transcript path;
-  without it the tool returns an actionable hint and captures nothing), plus
-  optional `cwd` and `session_id`.
-- **`query`** ("how does X work?") — reads the **salience-ranked Flows +
-  Decisions** for the configured repo via the F7.5 `read-decisions` endpoint
-  (authenticated with the `backthread_pat_` device token), and returns them **plus a
-  deep-link** into the web-app "How it works" diagram
-  (`https://app.backthread.dev/<owner>/<repo>`) so the founder can jump from CC to the
-  visual. Read-only. Args (all optional): `question` (narrated against the returned
-  log, not a server-side filter), `repo` (`owner/name` override; else `config.repo`,
-  else the cwd git remote), `cwd`. Unauthed → it reports "run `backthread login`" — it
-  **never** triggers a browser login itself (unlike the best-effort capture hook).
-Register it in `.claude/settings.json` (install-time wiring is F7.7 / ARP-438):
-```jsonc
-{
-  "mcpServers": {
-    "backthread": { "command": "npx", "args": ["backthread", "mcp"] }
-  }
-}
+```bash
+npx backthread install
 ```
-The server module (`src/mcp.ts`) is thin: the tool handlers delegate to
-`runCapture` / `queryDecisions` (their own modules + tests). Both handlers and the
-full tool wiring are unit-tested over the SDK's in-memory transport with mocked
-impls — no live network, no browser, no real auth.
-### How `cli/` accesses the redact/parse fence (architecture decision)
-The redaction fence is owned by `scripts/ingest/decisions/transcript.ts` (the
-F3/ARP-427 fence, behind the F7.11 provider seam). The `cli/` package, however,
-is a **separate, dependency-light bundle** whose distribution target is `npx backthread`
-— where **`scripts/` does not ship** — and its tsconfig pins `rootDir: src`, so a
-`../scripts/...` import would also break the build layout. So the fence is
-**vendored** into `cli/src/redact.ts` (+ the git-remote→repo parser into
-`cli/src/repo.ts`) as pure, zero-dependency copies. Parity with the canonical
-implementations is enforced by golden cases in `redact.test.ts` / `repo.test.ts`,
-so the two cannot silently drift.
-> **Distribution follow-up (flagged on ARP-433):** the vendored copy is the
-> pragmatic dogfood call, **not** the end state. The end state is a tiny shared
-> package (e.g. `@backthread/redact`) that both `scripts/ingest/decisions` and `cli/`
-> depend on, so the security fence has exactly **one** implementation. Until then,
-> a change to one fence must be mirrored in the other (the parity tests will fail
-> loudly if not). This is a follow-up ticket, not in-scope here.
+That's the whole setup. `install`:
-## Local config — `~/.backthread/config.json`
-Read by F7.2 / F7.3 / F7.4. Shape (all fields optional):
-```json
-{
-  "account": "<account uuid>",
-  "repo": "owner/name",
-  "device_token": "backthread_pat_…"
-}
-```
+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.
-Always written at `0600` (dir `~/.backthread` at `0700`).
+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.
-## Environment overrides (dev/testing)
+## Onboard yourself in 3 steps
-- `BACKTHREAD_APP_URL` — point the loopback at a local web app (e.g.
-  `http://localhost:5173`) instead of production.
-- `BACKTHREAD_WORKER_URL` — point the inference router at a local ingest Worker (e.g.
-  `http://localhost:8787` for `wrangler dev`) instead of production.
-- `BACKTHREAD_FUNCTIONS_URL` — point the Supabase Functions calls (`ingest-decisions`,
-  and the F7.4 `query` tool's `read-decisions`) at a local stack (e.g.
-  `http://localhost:54321/functions/v1`) instead of production.
-- `BACKTHREAD_CONFIG_DIR` — point the config at a temp dir instead of `~/.backthread`
-  (used by the unit tests; no real `$HOME` is touched).
+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).
-## Distribution choice (was open in ARP-432)
-**Default: `npx backthread`** — a standalone npm package with a `backthread` bin. Rationale:
-it's the most portable spine — the F7.2 hook, F7.3 slash command, and F7.4 MCP
-all shell out to / import the same bin regardless of which agent host invokes
-them, and `npx backthread login` works on any machine with Node. A **Claude Code
-plugin manifest** can wrap this bin later (it would just declare the hook +
-slash command and call `backthread`), so picking `npx backthread` now does not foreclose the
-plugin-manifest path — it's the lower layer underneath it. Per-agent adapters
-(Cursor/Codex) are explicitly later (Thread B / ARP-455→458).
-## `--device` fallback — STUBBED in F7.1
-The headless device-code flow (`gh`-style: "go to <url>, enter code ABCD-1234")
-needs a **server-side device-authorization endpoint** (a `/device/code` +
-`/device/token` pair) that does not exist yet — the F7.0 primitive (ARP-448)
-only ships the session-path mint. `backthread login --device` currently prints clear
-guidance (run `backthread login` with a browser, or mint from Account → Connected
-devices) and exits non-zero. Full impl is a follow-up.
-## Build / test
+## Commands
 ```
-npm --prefix cli install      # dev deps (tsx, typescript, @types/node, esbuild)
-npm --prefix cli run typecheck
-npm --prefix cli test         # node:test + tsx (NOT vitest)
-npm --prefix cli run build    # tsc → dist/         (dev + `npx backthread` path)
-npm --prefix cli run bundle   # esbuild → dist-bundle/backthread.js  (self-contained)
+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)
+backthread whoami    Show this device's config (your token is never printed)
+backthread capture   Capture a session's decisions (run automatically by the hook)
+backthread mcp       Start the MCP server — the capture + "how does X work?" query tools
+backthread help      Show usage
 ```
-The root `vitest run` excludes `cli/` (own test runner, like `worker/`).
-## Two build paths (8A.1 / ARP-474)
+## Requirements
-There are **two** ways to build the bin, for two distribution targets:
+- **Node.js ≥ 22.18**
-- **`npm run build` (tsc) → `dist/`** — the **dev + npm-package path**. Emits
-  multi-file `dist/` and resolves the one runtime dep
-  (`@modelcontextprotocol/sdk`) from `node_modules` at runtime. This is what
-  `npx backthread` uses (npm installs the dep tree), and what `dist/bin/backthread.js` — the
-  `package.json` `bin` target — points at.
-- **`npm run bundle` (esbuild) → `dist-bundle/backthread.js`** — the **self-contained
-  distribution path**. Bundles the bin **and** that runtime dep into a single
-  executable ESM file (`esbuild.config.mjs`: `--bundle --platform=node
-  --format=esm --target=node22`, tree-shaken so only the `server/mcp.js` +
-  `server/stdio.js` subpaths of the SDK are inlined). It runs with **no
-  `npm install`** — drop the one file anywhere with Node 22 and run it.
+## Learn more
-The bundle is what:
+- **Live app** — [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)
-- the **Claude Code plugin (8A.4)** references via
-  `${CLAUDE_PLUGIN_ROOT}/cli/dist-bundle/backthread.js` (so the plugin ships a runnable
-  bin without vendoring `node_modules`), and
-- a **future standalone binary** (Node SEA / `pkg`) wraps.
+## License
-Both `dist/` and `dist-bundle/` are git-ignored (regenerated from `src/`); both
-are listed in `package.json` `files` so they ship via npm/`npm pack`. A
-`prepack` script (`build && bundle`) regenerates both from current source
-whenever the package is packed, so a tarball never ships stale/empty `dist*`.
-The bundle does not replace the tsc build — they coexist for their two targets.
-esbuild is the only new devDep.
+[MIT](./LICENSE) © Backthread

package/dist-bundle/backthread.js CHANGED Viewed

@@ -7272,12 +7272,12 @@ function deviceLogin(log) {
       "Headless (--device) login is not available yet.",
       "",
       "The device-code fallback needs a server-side device-authorization endpoint",
-      "that ships in a later F7 task. For now, run `backthread login` on a machine with a",
+      "that ships in a later task. For now, run `backthread login` on a machine with a",
       "browser, or mint a token from the web app (Account \u2192 Connected devices) and",
       'place it in ~/.backthread/config.json under "device_token".'
     ].join("\n")
   );
-  return { ok: false, message: "--device fallback not implemented yet (F7.1 stub)." };
+  return { ok: false, message: "--device fallback not implemented yet." };
 }
 async function ensureAuth(opts = {}) {
   const env = opts.env ?? process.env;
@@ -7469,7 +7469,7 @@ async function serverInfer(transcript, config2, opts = {}) {
         Authorization: `Bearer ${token}`,
         "Content-Type": "application/json",
         ...versionHeaders()
-        // x-backthread-version — server-side compat guard (ARP-479)
+        // x-backthread-version — server-side compat guard
       },
       body: JSON.stringify(body)
     });
@@ -7974,7 +7974,7 @@ async function fetchOnboardingState(input = {}, deps = {}) {
           // never logged
           "Content-Type": "application/json",
           ...versionHeaders()
-          // x-backthread-version — server-side compat guard (ARP-479)
+          // x-backthread-version — server-side compat guard
         },
         // CLI shape: repo_slug = "owner/name". Omitted when no repo resolved.
         body: JSON.stringify(repo ? { repo_slug: `${repo.owner}/${repo.name}` } : {})
@@ -8314,10 +8314,10 @@ async function runCapture(input, deps = {}) {
       env,
       fetchImpl: deps.fetchImpl,
       log,
-      // Carry the session id so the connect-nudge (F7.10) can throttle once-per-session
+      // 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,
-      // 8B.5 first-capture confirmation seam (threaded so tests can stub it).
+      // first-capture confirmation seam (threaded so tests can stub it).
       firstCaptureConfirmImpl: deps.firstCaptureConfirmImpl
     });
   } catch (e) {
@@ -8346,7 +8346,7 @@ async function persistDerived(decisions, repo, config2, decidedAt, ctx) {
         // device token — never logged
         "Content-Type": "application/json",
         ...versionHeaders()
-        // x-backthread-version — server-side compat guard (ARP-479)
+        // x-backthread-version — server-side compat guard
       },
       body: JSON.stringify(body)
     });
@@ -32696,7 +32696,7 @@ async function queryDecisions(input, deps = {}) {
           Authorization: `Bearer ${config2.device_token}`,
           "Content-Type": "application/json",
           ...versionHeaders()
-          // x-backthread-version — server-side compat guard (ARP-479)
+          // x-backthread-version — server-side compat guard
         },
         body: JSON.stringify({ repo: { owner: repo.owner, name: repo.name } })
       });

package/hooks/hooks.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-  "$comment": "F7.7 / ARP-438 — 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 — 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.",
   "hooks": {
     "SessionEnd": [
       {

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "backthread",
-  "version": "0.1.0",
-  "description": "Backthread CLI — capture the *why* of your AI-coded changes from your Claude Code sessions, and query your codebase's architectural memory without leaving the terminal. Source code and tool I/O are redacted locally before anything leaves your machine.",
+  "version": "0.1.2",
+  "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",
   "homepage": "https://backthread.dev",