Capture dev context on interrupt; replay it as a 30-second resume card. Git stash for your head.
MCP Server: io.github.anthonysuherli/br8n
The br8n MCP server captures developer context when an interrupt occurs and replays it as a 30-second resume card. It functions like a “git stash for your head,” saving the branch, open files, the diff, and a one-line “why,” then presenting that summary when you return.
🛠️ Key Features
Saves branch
Records open files
Stores the diff
Captures a one-line “why” for the work
🚀 Use Cases
Recovering from interruptions without losing intent
Quickly resuming a task with a time-bounded resume summary (30-second card)
⚡ Developer Benefits
Reduces the cost of refocusing after an interruption (as stated in the excerpt)
Helps remember what a branch was “for” by preserving the original intent
⚠️ Limitations
Excerpt does not specify supported languages, integration methods, or any configuration options beyond installation.
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).
Core features
1. Capture — Save your thinking before you switch away
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.
2. Resume — Return to where you left off
Open br8n (or focus your editor). The resume card appears instantly with:
Your last hypothesis (the headline)
Recent snapshots (how many times were you here?)
A coverage band (how fresh is this knowledge?)
code
╔════════════════════════════════════╗
║ br8n — Where were you? ║
╠════════════════════════════════════╣
║ 📌 Fixing auth bug in login flow ║
║ ║
║ Recent snapshots: ║
║ • 5 min ago: auth middleware ║
║ • 12 min ago: jwt validation ║
║ • 45 min ago: session storage ║
║ ║
║ Coverage: ████░ (rich) ║
╚════════════════════════════════════╝
No digging through git logs. No "where was I again?" Back to work in 30 seconds.
3. Explore — Fill knowledge gaps
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.
code
Resume card says "coverage: gap"
│
▼
┌─────────────────┐
│ [Explore Now] │ ─► web search (changed deps, docs)
└─────────────────┘ ─► fetch + parse relevant sources
│ ─► extract + embed findings
▼
Coverage updates to "rich" + new context appears in the card
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.
Use it two ways
Claude Code plugin (on demand)
Slash commands from inside any Claude Code session:
code
/br8n:pickup → Show the current repo/branch resume card
/br8n:capture → Save a snapshot right now
/br8n:search <q> → Ask a question, grounded in your session history
/br8n:explore <topic> → Force the gap-fill pipeline
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.
iOS companion (read on the go)
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).
Knowledge engine: portable & accessible
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.
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.
Examples
Example 1: The meeting interruption
code
14:32 — Debugging auth middleware
Open file: middleware.py, line 45
Hypothesis: "JWT validation is caching stale tokens"
14:35 — [Meeting call]
/br8n:capture → br8n saves the snapshot
15:47 — [Back from meeting]
/br8n:pickup → resume card appears:
"🔸 JWT validation is caching stale tokens"
Recent context shown. No "where was I?" moment.
Example 2: Context switch across branches
code
You're on fix/session-timeout, about to switch to main
/br8n:capture → snapshot saved against this branch
Hours later, switch back:
git checkout fix/session-timeout
/br8n:pickup → resumes from that branch
→ shows the last hypothesis + snapshots
Example 3: In Claude Code
code
You're in a Claude Code session, ask a question:
/br8n:search "how did I set up the JWT secret?"
Claude Code queries your captured session history
and answers from your own notes/decisions.
Quick start
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
andTAVILY_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.
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.
Configuration
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).
Design principles
Intent over state — capture why, not just what (the hypothesis is the headline)
Low friction — one command checkpoints everything; no forms to fill out
Bounded capture — snapshot at the moments that matter (before a meeting, branch switch, end of day)
Survive context switches — works across folders, branches, machines
Never blocking — capture is fire-and-forget; <1s per snapshot
⬜ Apple sign-in, end-to-end — Fly.io deploy + Supabase Apple provider + iOS wiring (designed, in progress)
⬜ Cross-machine sync — designed, not yet shipped
⬜ Team sharing — designed, not yet shipped
License
br8n 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.