{
  "markdown": "# br8n — git stash for your head\n\n[**Site**](https://anthonysuherli.github.io/br8n/) · [install](https://anthonysuherli.github.io/br8n/install.html) · [how it works](https://anthonysuherli.github.io/br8n/how-it-works.html) · `pip install br8n`\n\n**You'll forget what this branch was for. br8n won't.** It saves what you were\nthinking the moment you get pulled away — branch, open files, the diff, and the\none-line *why* — and hands it back as a 30-second resume card when you return.\nYour code is already saved; this is the part that isn't. Research puts the cost of\nrefocusing after an interruption at about 23 minutes\n([Gloria Mark, UC Irvine](https://www.ics.uci.edu/~gmark/chi08-mark.pdf)),\nand longer for complex code. *(Snapshots are taken two ways today: automatically at \ncommit boundaries via an installed `post-commit` hook, and on demand with \n`/br8n:capture`. There is no continuous watcher.)*\n\nMost tools capture *state* (files, layout, git history). br8n captures *intent* — the \none-line hypothesis in your head: *\"JWT validation is caching stale tokens.\"* That's the \nwedge that matters.\n\nBeyond your current device, br8n is a **portable knowledge engine**: your captured \ninsights live in a searchable journal accessible from Claude Code, the iOS companion, or \nany tool that speaks HTTP. Sync, search, and share across machines (paid tier, future).\n\n## Core features\n\n### 1. Capture — Save your thinking before you switch away\n\nBefore a meeting, a branch switch, or end of day, run `/br8n:capture`. br8n snapshots \nyour workspace in one second and records *\"What were you working on?\"* — the one-line \nhypothesis is the load-bearing field.\n\n```\nBefore:                    Capture:                   After:\n┌─────────────────┐    /br8n:capture          ┌──────────────────┐\n│ Fixing bug in   │  ───► br8n asks:  ───►  │ Finding saved:   │\n│ auth flow       │       \"What were    │      │ • git diff       │\n│ files: [3]      │       you doing?\"   │      │ • open files     │\n│ branch: fix-#42 │       Fixing auth   │      │ • cursor pos     │\n└─────────────────┘       bug            │      │ • hypothesis     │\n                                         └──────────────────┘\n                                         (stored in KB)\n```\n\nYour captured snapshots live in a searchable journal. One hypothesis per snapshot—\nthe thing you'd write on a post-it.\n\n### 2. Resume — Return to where you left off\n\nOpen br8n (or focus your editor). The resume card appears instantly with:\n- Your **last hypothesis** (the headline)\n- **Recent snapshots** (how many times were you here?)\n- A **coverage band** (how fresh is this knowledge?)\n\n```\n╔════════════════════════════════════╗\n║ br8n — Where were you?           ║\n╠════════════════════════════════════╣\n║ 📌 Fixing auth bug in login flow   ║\n║                                    ║\n║ Recent snapshots:                  ║\n║   • 5 min ago: auth middleware     ║\n║   • 12 min ago: jwt validation     ║\n║   • 45 min ago: session storage    ║\n║                                    ║\n║ Coverage: ████░ (rich)             ║\n╚════════════════════════════════════╝\n```\n\nNo digging through git logs. No \"where was I again?\" Back to work in 30 seconds.\n\n### 3. Explore — Fill knowledge gaps\n\nIf coverage is `gap` (you've been away a while, or switched branches), one click runs \na web-research pipeline to pull in fresh context: changed docs, new issues, updated \ndeps—and folds it back into your session knowledge base.\n\n```\nResume card says \"coverage: gap\"\n         │\n         ▼\n┌─────────────────┐\n│ [Explore Now]   │  ─► web search (changed deps, docs)\n└─────────────────┘  ─► fetch + parse relevant sources\n         │            ─► extract + embed findings\n         ▼\nCoverage updates to \"rich\" + new context appears in the card\n```\n\nPerfect for returning after a weekend or after your teammate merged a big change.\n\n---\n\nbr8n is a self-contained fork of [Delapan](../delapan), repurposing its \nprimitives (Findings, pgvector search, tap/preamble) from chat to automatic capture.\n\n## Use it two ways\n\n### Claude Code plugin (on demand)\nSlash commands from inside any Claude Code session:\n\n```\n/br8n:pickup          →  Show the current repo/branch resume card\n/br8n:capture         →  Save a snapshot right now\n/br8n:search <q>      →  Ask a question, grounded in your session history\n/br8n:explore <topic> →  Force the gap-fill pipeline\n```\n\nExample: 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.\n\n### iOS companion (read on the go)\nA native SwiftUI app — the read spine. **Sign in with Apple**, browse your cross-repo \nactivity, and read resume cards from your phone. Consumes the same `/v1/projects` + \n`/v1/resume` + `/v1/activity` API, authenticated per-user (see below).\n\n## Knowledge engine: portable & accessible\n\nYour captured snapshots form a **searchable knowledge journal**. The engine runs in two tiers \nfrom the same code — the difference is where your data lives.\n\n| Tier | Free / local | Paid / cloud |\n|---|---|---|\n| **Storage** | On-device SQLite | Hosted Supabase (pgvector) |\n| **Access** | Loopback only (`localhost:8002`) | Anywhere (with API key) |\n| **Sign-in** | None | GoTrue |\n| **Data** | `~/.br8n/brain.db` | Encrypted, RLS protected |\n| **Select** | `BR8N_BACKEND=local` | `BR8N_BACKEND=cloud` + creds |\n\n**Access your knowledge anywhere:**\n\n```\nClaude Code (local/cloud)     iOS companion (cloud)     Browser (cloud, future)\n     │                              │                            │\n     └──────────────┬───────────────┴───────────────────────┘\n                    │\n              br8n API\n                    │\n            ┌───────┴────────┐\n            │                │\n        SQLite          Supabase\n      (local db)      (cloud db)\n```\n\nFree tier: single device, no sync. Paid tier: access from Claude Code, the iOS app, or \nany tool that speaks HTTP. Team sharing and cross-repo search are designed (future).\n\nThe paid value props — **cross-machine sync**, **cross-repo search**, **managed keys**, \n**team sharing** — are not yet shipped.\n\n## Examples\n\n### Example 1: The meeting interruption\n```\n14:32 — Debugging auth middleware\n        Open file: middleware.py, line 45\n        Hypothesis: \"JWT validation is caching stale tokens\"\n        \n14:35 — [Meeting call]\n        /br8n:capture → br8n saves the snapshot\n        \n15:47 — [Back from meeting]\n        /br8n:pickup → resume card appears:\n        \"🔸 JWT validation is caching stale tokens\"\n        Recent context shown. No \"where was I?\" moment.\n```\n\n### Example 2: Context switch across branches\n```\nYou're on fix/session-timeout, about to switch to main\n    /br8n:capture → snapshot saved against this branch\n    \nHours later, switch back:\n    git checkout fix/session-timeout\n    /br8n:pickup → resumes from that branch\n    → shows the last hypothesis + snapshots\n```\n\n### Example 3: In Claude Code\n```\nYou're in a Claude Code session, ask a question:\n    /br8n:search \"how did I set up the JWT secret?\"\n    \nClaude Code queries your captured session history\n    and answers from your own notes/decisions.\n```\n\n---\n\n## Quick start\n\nInstall the Claude Code plugin — no venv, no path editing. The plugin's MCP server \nbootstraps its own environment on first run.\n\n```\n/plugin marketplace add anthonysuherli/br8n\n/plugin install br8n@br8n\n```\n\nReload the session, then use `/br8n:pickup`, `/br8n:capture`, etc. Data lives in \n`~/.br8n/brain.db` on the free/local tier.\n\n**What works without any key:** capture and resume. Snapshots are stored without \nembeddings, so the resume card, the hypothesis and the snapshot trail all work with no \naccount and no key at all.\n\n**What needs a key:** semantic search (`/br8n:search`) needs an embedding key — \n`AI_GATEWAY_API_KEY` or `OPENAI_API_KEY`. The explore / gap-fill pipeline needs that \n*and* `TAVILY_API_KEY` for web search.\n\n**Keyless semantic search:** on the local tier, `pip install 'br8n[local-embeddings]'` \ngives you semantic search with no API key at all — an on-device ONNX model \n(bge-small-en-v1.5, ~130MB, no torch, downloaded once on first use). Use \n`/br8n:embeddings` to check which provider is active or switch between them. A keyless \n`python -m br8n.vault.reindex` rebuilds real vectors, not just text.\n\nVectors from different models aren't comparable, so br8n keeps **one active embedding \nspace** and re-embeds when you change providers. Because a provider can also change \n*by accident* — a shell without your API key resolves to the local model — br8n will \nnot silently throw your vectors away: a change it inferred from the environment is \n**offered**, not applied. `/br8n:embeddings` (and `--check`) report the pending switch, \nand it happens when you confirm. While an offer is pending, capture and search behave \nexactly as they do with no key at all: nothing breaks, nothing is lost, and the \nbacklog re-embeds itself once you confirm. A switch you ask for explicitly applies \nimmediately.\n\nSanity-check a local install with `python -m br8n.api.main --check` — it reports your \nPython version, which backend tier is configured, whether `sqlite-vec` loads, whether \nthe DB path is writable, and whether the embedding and explore keys are present. \nAnything missing is named explicitly.\n\n### Running the API directly (optional)\n\n**Free/local** (SQLite, single device):\n```bash\nBR8N_BACKEND=local python -m br8n.api.main   # listens 127.0.0.1:8002\n```\n\n**Paid/cloud** (Supabase, accessible anywhere):\n```bash\nBR8N_BACKEND=cloud uvicorn br8n.api.main:app --reload --port 8002\n```\n\n### From source (contributors)\n\nWorking on br8n itself, rather than using it:\n\n```bash\ngit clone https://github.com/anthonysuherli/br8n\ncd br8n/backend\npython3.11 -m venv .venv\n.venv/bin/pip install -e \".[dev]\"\ncp .env.example .env\n```\n\n`pip install br8n` also works as a plain package install, and ships the\n`br8n-mcp` and `br8n-server` entry points; the plugin marketplace remains the\nsupported path for using br8n inside Claude Code.\n\n## Configuration\n\nBy default, the knowledge base is keyed by **project** (git repo name) and **kb** \n(git branch). Override the database path with `BR8N_DB_PATH` (local) or set Supabase \ncredentials in `.env` (cloud).\n\nThe **cloud tier is multi-user**: each request carries a Supabase GoTrue JWT — \nobtained via **Sign in with Apple** through `POST /v1/auth/apple` (Supabase verifies \nthe Apple token and provisions the user) and rotated via `POST /v1/auth/refresh`. The \nbackend verifies the JWT against `SUPABASE_JWT_SECRET` and scopes every read/write \n(findings *and* the activity graph) to the caller's own org via row-level security. \n`BR8N_API_KEY` remains as a service-only key for internal callers. The **local tier** \nneeds no auth (loopback-only, single user).\n\n## Design principles\n\n- **Intent over state** — capture why, not just what (the hypothesis is the headline)\n- **Low friction** — one command checkpoints everything; no forms to fill out\n- **Bounded capture** — snapshot at the moments that matter (before a meeting, branch switch, end of day)\n- **Survive context switches** — works across folders, branches, machines\n- **Never blocking** — capture is fire-and-forget; <1s per snapshot\n\n## Architecture & development\n\nSee [`CLAUDE.md`](CLAUDE.md) for:\n- Module layout (`br8n/` core engine, fork structure)\n- API surface (`/v1/capture`, `/v1/resume`, `/v1/explore`, `/v1/auth/apple`)\n- Storage tiers (SQLite vs Supabase)\n- MCP tools and plugin skills\n\n## Status\n\n- [x] **Core engine** — capture, resume, explore pipelines\n- [x] **Claude Code plugin** — slash commands (`/br8n:pickup`, etc.)\n- [x] **iOS companion** — native SwiftUI read spine (projects, resume cards, activity)\n- [x] **Storage tiers** — free (SQLite) and paid (Supabase) in one codebase\n- [x] **Multi-user cloud auth (backend)** — per-user Supabase JWT tenancy, per-org isolation, `/v1/auth/apple` + `/v1/auth/refresh`\n- ⬜ **Apple sign-in, end-to-end** — Fly.io deploy + Supabase Apple provider + iOS wiring (designed, in progress)\n- ⬜ **Cross-machine sync** — designed, not yet shipped\n- ⬜ **Team sharing** — designed, not yet shipped\n\n## License\n\nbr8n is open source under the [MIT License](LICENSE) — use it for anything,\nincluding commercially, as long as the copyright notice is preserved.\n\n\"br8n\" is a name used by Anthony Suherli; the license covers the code, not the\nname (see [TRADEMARKS.md](.github/TRADEMARKS.md)). br8n is a self-contained fork of the\nDelapan engine; Delapan itself is separately licensed and not covered by this\nMIT grant.\n\nContributions are welcome under the inbound = outbound rule with a DCO sign-off\n— see [CONTRIBUTING.md](.github/CONTRIBUTING.md). For the full governance map (security\ndisclosure, privacy, code of conduct), see [LEGAL.md](.github/LEGAL.md).\n",
  "bytes": 12834,
  "sha": "ddea3a22047595c39b724620b3522e042eac9c6bea4c1476564c1c115b920e40",
  "repo_slug": "anthonysuherli/br8n",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_anthonysuherli_br8n_7e393a48/readme"
}