The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Br8n listing page.
Site · install · how it works · pip install br8n
You'll forget what this branch was for. br8n won't. It saves what you were
thinking the moment you get pulled away — branch, open files, the diff, and the
one-line why — and hands it back as a 30-second resume card when you return.
Your code is already saved; this is the part that isn't. Research puts the cost of
refocusing after an interruption at about 23 minutes
(Gloria Mark, UC Irvine),
and longer for complex code. (Snapshots are taken two ways today: automatically at
commit boundaries via an installed post-commit hook, and on demand with
/br8n:capture. There is no continuous watcher.)
Most tools capture state (files, layout, git history). br8n captures intent — the one-line hypothesis in your head: "JWT validation is caching stale tokens." That's the wedge that matters.
Beyond your current device, br8n is a portable knowledge engine: your captured insights live in a searchable journal accessible from Claude Code, the iOS companion, or any tool that speaks HTTP. Sync, search, and share across machines (paid tier, future).
Before a meeting, a branch switch, or end of day, run /br8n:capture. br8n snapshots
your workspace in one second and records "What were you working on?" — the one-line
hypothesis is the load-bearing field.
Your captured snapshots live in a searchable journal. One hypothesis per snapshot— the thing you'd write on a post-it.
Open br8n (or focus your editor). The resume card appears instantly with:
No digging through git logs. No "where was I again?" Back to work in 30 seconds.
If coverage is gap (you've been away a while, or switched branches), one click runs
a web-research pipeline to pull in fresh context: changed docs, new issues, updated
deps—and folds it back into your session knowledge base.
Perfect for returning after a weekend or after your teammate merged a big change.
br8n is a self-contained fork of Delapan, repurposing its primitives (Findings, pgvector search, tap/preamble) from chat to automatic capture.
Slash commands from inside any Claude Code session:
Example: You're in a Claude Code session debugging auth. Type /br8n:search "how did I set up JWT validation?" and get an answer from your captured snapshots.
A native SwiftUI app — the read spine. Sign in with Apple, browse your cross-repo
activity, and read resume cards from your phone. Consumes the same /v1/projects +
/v1/resume + /v1/activity API, authenticated per-user (see below).
Your captured snapshots form a searchable knowledge journal. The engine runs in two tiers from the same code — the difference is where your data lives.
| Tier | Free / local | Paid / cloud |
|---|---|---|
| Storage | On-device SQLite | Hosted Supabase (pgvector) |
| Access | Loopback only (localhost:8002) | Anywhere (with API key) |
| Sign-in | None | GoTrue |
| Data | ~/.br8n/brain.db | Encrypted, RLS protected |
| Select | BR8N_BACKEND=local | BR8N_BACKEND=cloud + creds |
Access your knowledge anywhere:
Free tier: single device, no sync. Paid tier: access from Claude Code, the iOS app, or any tool that speaks HTTP. Team sharing and cross-repo search are designed (future).
The paid value props — cross-machine sync, cross-repo search, managed keys, team sharing — are not yet shipped.
Install the Claude Code plugin — no venv, no path editing. The plugin's MCP server bootstraps its own environment on first run.
Reload the session, then use /br8n:pickup, /br8n:capture, etc. Data lives in
~/.br8n/brain.db on the free/local tier.
What works without any key: capture and resume. Snapshots are stored without embeddings, so the resume card, the hypothesis and the snapshot trail all work with no account and no key at all.
What needs a key: semantic search (/br8n:search) needs an embedding key —
AI_GATEWAY_API_KEY or OPENAI_API_KEY. The explore / gap-fill pipeline needs that
and TAVILY_API_KEY for web search.
Keyless semantic search: on the local tier, pip install 'br8n[local-embeddings]'
gives you semantic search with no API key at all — an on-device ONNX model
(bge-small-en-v1.5, ~130MB, no torch, downloaded once on first use). Use
/br8n:embeddings to check which provider is active or switch between them. A keyless
python -m br8n.vault.reindex rebuilds real vectors, not just text.
Vectors from different models aren't comparable, so br8n keeps one active embedding
space and re-embeds when you change providers. Because a provider can also change
by accident — a shell without your API key resolves to the local model — br8n will
not silently throw your vectors away: a change it inferred from the environment is
offered, not applied. /br8n:embeddings (and --check) report the pending switch,
and it happens when you confirm. While an offer is pending, capture and search behave
exactly as they do with no key at all: nothing breaks, nothing is lost, and the
backlog re-embeds itself once you confirm. A switch you ask for explicitly applies
immediately.
Sanity-check a local install with python -m br8n.api.main --check — it reports your
Python version, which backend tier is configured, whether sqlite-vec loads, whether
the DB path is writable, and whether the embedding and explore keys are present.
Anything missing is named explicitly.
Free/local (SQLite, single device):
Paid/cloud (Supabase, accessible anywhere):
Working on br8n itself, rather than using it:
pip install br8n also works as a plain package install, and ships the
br8n-mcp and br8n-server entry points; the plugin marketplace remains the
supported path for using br8n inside Claude Code.
By default, the knowledge base is keyed by project (git repo name) and kb
(git branch). Override the database path with BR8N_DB_PATH (local) or set Supabase
credentials in .env (cloud).
The cloud tier is multi-user: each request carries a Supabase GoTrue JWT —
obtained via Sign in with Apple through POST /v1/auth/apple (Supabase verifies
the Apple token and provisions the user) and rotated via POST /v1/auth/refresh. The
backend verifies the JWT against SUPABASE_JWT_SECRET and scopes every read/write
(findings and the activity graph) to the caller's own org via row-level security.
BR8N_API_KEY remains as a service-only key for internal callers. The local tier
needs no auth (loopback-only, single user).
See CLAUDE.md for:
br8n/ core engine, fork structure)/v1/capture, /v1/resume, /v1/explore, /v1/auth/apple)/br8n:pickup, etc.)/v1/auth/apple + /v1/auth/refreshbr8n is open source under the MIT License — use it for anything, including commercially, as long as the copyright notice is preserved.
"br8n" is a name used by Anthony Suherli; the license covers the code, not the name (see TRADEMARKS.md). br8n is a self-contained fork of the Delapan engine; Delapan itself is separately licensed and not covered by this MIT grant.
Contributions are welcome under the inbound = outbound rule with a DCO sign-off — see CONTRIBUTING.md. For the full governance map (security disclosure, privacy, code of conduct), see LEGAL.md.