backthread

Backthread keeps the thread on what your AI coding agent ships — it captures the why behind every change and turns it into a living 'How it works' view of your codebase you can actually query.

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 app.backthread.dev — see the live demo.

Your source code never leaves your machine

Backthread reads your agent transcripts, not your repo. Before anything is sent, the CLI redacts every transcript locally:

• 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].

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.

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) so you can verify it — read more at backthread.dev/security.

What npx backthread does

The bare command is the unified front door. Under the hood it:

1. Signs you in — opens your browser for one click (you'll need a free Backthread 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 from the terminal (backthread how "how does auth work?") or inside Claude Code (the backthread MCP server exposes a query tool + a /backthread:how slash command), or open the live diagram at app.backthread.dev.

Claude Code plugin (alternative)

Prefer the marketplace? 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.

Learn your own codebase (/backthread:learn)

/backthread:learn runs a short lesson about this repo, built from what was actually recorded here — the decisions, the reasoning, the options that were rejected. You answer a few questions in your own words; each one gets a plain "Got it" / "Not yet" and then the recorded reasoning, which is the part worth having. Nothing is scored, nothing is ranked, and no history of wrong answers is kept. "I disagree" and "Bad question" are always available and cost you nothing — the record can be the thing that's wrong. On a quiet week you get a short teaching card, or simply "you're caught up": that's a finished lesson, not a failed one.

One question while you wait (/backthread:ask-me)

The other direction. /backthread:ask-me has Backthread ask you one question about this codebase, from what was actually recorded here. The plugin also offers one, unprompted, when your agent is mid-errand rather than mid-edit — after a Bash, Task, WebFetch or WebSearch call, the kind of step you sit and watch. At most once per session.

Ignore it and nothing happens, and that is a property of the code rather than a policy. backthread ask-me --promise prints the exact statement, and it is worth reading there rather than here: it comes from the server that enforces it, so it cannot drift from the behaviour it describes the way a README can. In outline — nothing is written down when you are asked, nothing counts how often you are asked or answer, and your lead sees what each person understands rather than how much anyone took part.

What that rests on, mechanically: the endpoint that hands your agent a question performs no writes at all — the question exists only inside a signed, half-hour token, and Backthread keeps no copy of it. Backthread stores nothing on your machine either; diff its config directory across an ask you answered and one you ignored and you get the same bytes, which is exactly what the tests do. The whole client is cli/src/inflow.ts and cli/src/inflowHook.ts if you would rather check than take our word for it — same reason the redactor is open source. Two boundaries worth stating rather than glossing: the question is handed to you as hook context, so your coding agent writes it into its own session transcript the way it does everything else it is told (that file is the agent's, and Backthread's capture never uploads it); and what the server does with an answer is not checkable from this repo, which is why the statement is written as things you could go and check rather than as reassurance.

One honest caveat about "once per session": the machine remembers the last few dozen session ids, so a session resumed long afterwards can be offered a second question. Rare, bounded, and written down rather than glossed.

It is never a pre-edit trigger. The ask fires after a Bash, Task, WebFetch or WebSearch call, never before one and never around Edit / Write / MultiEdit. Nobody should be stopped before they want to touch anything.

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 config so capture follows you across every repo and git worktree:

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 instead, and Codex users the plugin.

Commands

backthread                     Set up Backthread — the front door (sign in + connect + capture).
                               Idempotent: a returning user is told they're good to go.
backthread how "<question>"    Ask how/why something works — a grounded, cited answer from your log
backthread install             Set up capture for this repo (sign in + hook + backfill)
backthread login / logout      Authorize this device / sign it out (drops the local token)
backthread doctor              Diagnose your setup (auth, hook, connectivity, version, repo)
backthread update              Update a global install to the latest (also -u)
backthread version             Print the installed version (also --version, -v)
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 graph               Refresh the repo-local structure cache (offline, incremental)
backthread sync                Sync this repo's merged decision "why" into the local cache (hours-TTL)
backthread help                Show the full usage (also --help, -h)

Global flags

--verbose                      When something fails, also print the operator detail: the HTTP
                               status, our internal error code, the retry reason, and the
                               database's own SQLSTATE when there is one.

Off by default, because those name our call sites and there is nothing you can do with them. What you get by default is a sentence that answers the only question a failure raises — whether trying again is worth it, and if not, what to do instead. BACKTHREAD_VERBOSE=1 is the same switch, and the MCP tools read it too (they have no command line to pass a flag on).

Requirements

• Node.js ≥ 22.18

Learn more

• Live app & demo — app.backthread.dev · app.backthread.dev/demo
• Marketing site — backthread.dev
• How your data is handled — backthread.dev/security
• Source & internals — github.com/backthread/backthread

License

MIT © Backthread