br8n — git stash for your head

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).

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.

Before:                    Capture:                   After:
┌─────────────────┐    /br8n:capture          ┌──────────────────┐
│ Fixing bug in   │  ───► br8n asks:  ───►  │ Finding saved:   │
│ auth flow       │       "What were    │      │ • git diff       │
│ files: [3]      │       you doing?"   │      │ • open files     │
│ branch: fix-#42 │       Fixing auth   │      │ • cursor pos     │
└─────────────────┘       bug            │      │ • hypothesis     │
                                         └──────────────────┘
                                         (stored in KB)

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?)

╔════════════════════════════════════╗
║ 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.

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:

/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.

Access your knowledge anywhere:

Claude Code (local/cloud)     iOS companion (cloud)     Browser (cloud, future)
     │                              │                            │
     └──────────────┬───────────────┴───────────────────────┘
                    │
              br8n API
                    │
            ┌───────┴────────┐
            │                │
        SQLite          Supabase
      (local db)      (cloud db)

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

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

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

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.

/plugin marketplace add anthonysuherli/br8n
/plugin install br8n@br8n

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.

Running the API directly (optional)

Free/local (SQLite, single device):

BR8N_BACKEND=local python -m br8n.api.main   # listens 127.0.0.1:8002

Paid/cloud (Supabase, accessible anywhere):

BR8N_BACKEND=cloud uvicorn br8n.api.main:app --reload --port 8002

From source (contributors)

Working on br8n itself, rather than using it:

git clone https://github.com/anthonysuherli/br8n
cd br8n/backend
python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"
cp .env.example .env