# br8n [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/anthonysuherli/br8n  
**GitHub Stars:** 1  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/br8n

## Description
Capture dev context on interrupt; replay it as a 30-second resume card. Git stash for your head.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "br8n": {
    "command": "uvx",
    "args": ["br8n"],
    "env": {
      "BR8N_BACKEND": "",
      "AI_GATEWAY_API_KEY": "",
      "OPENAI_API_KEY": "",
      "TAVILY_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `BR8N_BACKEND`, `AI_GATEWAY_API_KEY`, `OPENAI_API_KEY`, `TAVILY_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What br8n MCP server does

The br8n MCP server records the intent behind a development session rather than only preserving repository state. A snapshot can include the active Git branch, open files, cursor position, current diff, and the developer's one-line explanation of what they are trying to solve. That explanation becomes the main heading on a resume card.

The system is designed for interruptions and context switches. After returning to a repository, the pickup command shows the latest hypothesis, recent snapshots, and an indication of how fresh or complete the available context is. This can help reconstruct work after a meeting, a branch change, or a long gap.

## How it works

Snapshots are created in two ways: automatically at commit boundaries through an installed `post-commit` hook, or manually with `/br8n:capture`. The project does not continuously watch the workspace. Captured records are stored in a searchable journal and associated with the repository and branch context.

The Claude Code plugin exposes these commands:

- `/br8n:pickup` displays the current repository and branch resume card.
- `/br8n:capture` saves a new snapshot and asks what the developer was working on.
- `/br8n:search <q>` queries captured session history.
- `/br8n:explore <topic>` starts a gap-filling research flow.
- `/br8n:embeddings` reports or changes the active embedding provider.

When coverage is marked as a gap, the explore flow can search the web, retrieve relevant sources, parse them, and add extracted findings to the session knowledge base. Semantic search can use an external embedding key or an on-device model on the local tier.

## Setup and configuration

Install the Claude Code plugin with:

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

After reloading the session, the plugin bootstraps its own environment. The local tier stores data at `~/.br8n/brain.db` and serves it through a loopback API at `localhost:8002`. Set `BR8N_BACKEND=local` for that mode. The cloud tier uses Supabase and requires `BR8N_BACKEND=cloud` together with the relevant credentials.

Basic capture and resume require no key. External semantic search can use `AI_GATEWAY_API_KEY` or `OPENAI_API_KEY`. The explore pipeline also requires `TAVILY_API_KEY`. For keyless local semantic search, install the optional `br8n[local-embeddings]` package; it downloads an approximately 130 MB ONNX model on first use.

## Tools and capabilities

The br8n MCP server supports local capture and resume, branch-specific context recovery, searchable snapshots, and optional research for stale context. Its local embedding mode keeps semantic search on the device. A cloud configuration provides authenticated access to the same API for supported companion clients and HTTP-speaking tools.

The resume card reports recent snapshot activity and a coverage level. Search answers are grounded in captured session history rather than general repository history alone. The journal can therefore preserve decisions and hypotheses that are not represented in commits or files.

## Limitations and notes

The local tier is intended for one device and does not synchronize data. Cross-machine synchronization, cross-repository search, managed keys, and team sharing are described as future or paid capabilities rather than currently shipped features. The iOS companion consumes the cloud API and uses per-user authentication, so it is not a replacement for the local-only setup.

Only one embedding space is active at a time. Changing providers requires re-embedding because vectors from different models cannot be compared. If br8n detects an accidental provider change caused by a missing API key, it offers the switch instead of applying it silently. Until confirmation, capture and search continue without embeddings and existing data is retained.

The br8n MCP server is most suitable for developers using Claude Code who want lightweight interruption recovery and a journal of their own working hypotheses.

_Full upstream README: https://allmcps.com/mcp/br8n/readme_

