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 backthreadOne 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" view. Re-run it anytime — it's idempotent.
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.
You delegate code to an agent (Claude Code, Cursor, Codex). It ships. You skim the diff, approve, move on. Three or four weeks later you own a codebase full of decisions you nominally made but never actually internalized — and now debugging is slow and every refactor is a coin flip.
Backthread captures the why behind each change straight from your agent sessions — the trade-offs, the rejected approaches, the "we did it this way because…" — and turns it into a living "How it works" view of your system: a diagram + changelog at app.backthread.dev, plus a how command you can ask right from the terminal. Try the live demo.
Your source code never leaves your machine unredacted — that's the whole point, and it's auditable right here.
- You're a founder or CTO who's been vibecoding with an agent for weeks and can no longer fully explain your own system.
- Your team ships agent PRs faster than anyone can actually review them, and nobody holds the whole architecture in their head anymore.
- You're about to refactor or debug a part of the codebase you didn't write by hand and need the why before you touch it.
- You want to onboard a teammate (or your future self) to how a system works without a week of PR archaeology.
- You want to ask "how does auth work?" or "why is billing structured this way?" and get a cited answer from your own history — not a fresh guess.
You already have ways to reconstruct the why. They just don't keep up with agent velocity:
- vs. re-reading PRs & commit archaeology — the diff shows what changed, never why — and at agent speed there are far too many to read. Backthread captures the why as it happens.
- vs. re-interrogating the agent — a fresh session doesn't remember last month's reasoning; it re-derives (and re-hallucinates) it. Backthread keeps the actual decision, dated and cited.
- vs. docs that rot the day they're written — hand-maintained docs drift the moment the next PR lands. Backthread's view is rebuilt from your real history, so it tracks the code instead of lying about it.
Backthread isn't a code-review tool — it lives above the diff, on the architecture.
npx backthread # sign in + connect this repo + wire up capture (~60 seconds)That's the whole setup. From then on Backthread captures the why behind each session automatically. Then, whenever you're lost:
backthread how "how does auth work?" # a grounded, cited answer from your own decision log…and open your live "How it works" view at app.backthread.dev.
Not sure what's wired up? npx backthread doctor tells you exactly what's set up and what isn't.
| Command | What it does |
|---|---|
backthread |
The front door: sign in, connect this repo, wire up capture. Idempotent — re-run anytime. |
backthread how "<question>" |
Ask how/why something works — a grounded, cited answer from your decision log. |
backthread login / backthread logout |
Authorize this device (one browser click) / sign it out (drops the local token, keeps the repo link). |
backthread install |
Set up capture for this repo (--agent codex|cursor|gemini wires up other agents). |
backthread doctor |
Diagnose your setup — auth, capture hook, connectivity, version, repo — with ✓/✗ + fixes. |
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 (never prints the token). |
backthread mcp |
Start the MCP server (the capture + how/query tools) over stdio. |
backthread help |
The full list (also --help, -h). |
| Package | npm | What it is |
|---|---|---|
cli |
backthread |
The npx backthread CLI — captures the why of your changes from your agent sessions and answers "how does X work?" from the terminal. |
packages/redact |
@backthread/redact |
The redaction fence — pure, zero-dependency string transforms that strip source code and tool I/O out of a session transcript before anything leaves your machine. |
The redaction fence and the CLI are the parts of Backthread that run on your machine and see your code. The trust claim — "source code and tool I/O never leave your machine unredacted" — is only worth as much as your ability to verify it. So this code is public: read it, audit it, run it. Verify us, don't trust us.
The structural extractor that derives the architecture view will join this repo as @backthread/extractor (not yet published) — polyglot by design (TypeScript today, more languages behind a pluggable adapter seam).
Found a hole in that promise? Report it privately — see SECURITY.md (or GitHub's "Report a vulnerability" button). How your data is handled end to end: backthread.dev/security.
The short version: your source and tool I/O never leave your machine unredacted — the @backthread/redact fence strips them locally, before anything is sent, and the device token is stored owner-only (chmod 0600) and sent only as an auth header, never in a URL or log.
- Node.js ≥ 22.18 — the redaction fence ships as source-only TypeScript and relies on Node's default type stripping. The CLI talks only to public endpoints (
app.backthread.dev+ its ingest worker); no secrets are embedded in this source.
- Live app & demo — app.backthread.dev · app.backthread.dev/demo
- Marketing site — backthread.dev
- How your data is handled — backthread.dev/security
- CLI on npm — npmjs.com/package/backthread
MIT © Backthread