Stack256 · 007

Your docs are nodes in your code graph.

Every code-intelligence tool can tell you what calls what. None can tell you that your landing page still advertises the feature you renamed last Tuesday. Brainer indexes your code and your prose into one graph, so changing a function shows you the paragraph that just became a lie.

Source on GitHub → How to use it

What makes it different

There is no shortage of tools that turn a codebase into a graph. Every one of them stops at the code. Brainer's graph has a node type none of them have: prose.

  • Prose is a first-class node

    A heading and its body, a README section, a line of landing-page copy — indexed, linked to the symbols it describes, and traversed like any other edge.

  • Confidence you can act on

    A similarity score of 0.50 sounds like a coin flip. Measured against a labelled set, it means the link is right 98% of the time. Brainer reports the probability, not the raw number.

  • Nothing leaves your machine

    Embeddings run on-device from a 24MB model. No API key, no account, no network after the one-time download — so it works offline and inside cloud agent sessions without secrets.

It also stops your agent searching blind

An agent starting a task greps, globs, reads, discards, and greps again. Every round costs tokens, and it still misses things. One graph query replaces the loop — and because Brainer runs before the agent starts, nobody has to remember to ask for it.

Files found that mattered 94%, against 48% for a keyword search
Tokens spent finding them 12.8k, against 21.1k grepping — and 8× cheaper than reading the repo
Cost of leaving it always on 36 tokens per turn; one grep round-trip is 800–2000
Works with Claude Code, Codex, Cursor, Copilot, Zed, Windsurf — over MCP, skills, hooks, or plain CLI

Using it

Install it, wire up every agent on the machine, and build the index. After that it runs on its own.

  1. Install and wire it up

    Detects Claude Code, Cursor, VS Code, Zed and the shared skills directory, and writes the right config to each. 

    npm install -g @stack256org/brainer
brainer install

  2. Build the index

    Walks the repository, parses it, embeds the cards and links prose to code. About eight seconds for a mid-size project. 

    brainer init

  3. Ask it things

    Or do not — with hooks installed, relevant files are surfaced before you search, and affected documentation is reported after you edit. 

    brainer context "add rate limiting to login"
brainer surfaces getSession
brainer serve

What it needs

Runtime Node.js 20+ — nothing else
Network One 24MB model download, then never again. No API key, no account, no telemetry
Storage A single SQLite file in .brainer/, gitignored
Languages TypeScript, TSX, JavaScript, JSX; Markdown, MDX and HTML for prose
Architectures x86_64 and arm64
Licence MIT

What it will not do

Some prose describes a project as a whole and points at no code at all — roughly a sixth of a typical landing page. Brainer returns nothing for those rather than inventing a link, and a semantic guess is always labelled as a guess until you confirm it. The file list it hands an agent is a starting point, not a promise that nothing else matters.

Source on GitHub → How it was measured The Next.js starter →