SpiderBrain: the understanding layer for your repo

A repo tells an AI agent what the code is. It never tells it what matters, what a change reaches, or why anything was built the way it was. So every agent re-derives the structure from scratch, every session, and gets it a little wrong.

SpiderBrain gives a repo a committed, source-free understanding layer: a deterministic map of its structure, dependencies, and blast radius that any AI coding agent can read with zero setup. This repository is the open, MIT-licensed part of that layer: the reader, and the format specification.

• Website: https://spiderbrain.ai
• Determinism benchmark: https://contextbenchmark.com

Use it in one line

When a repo carries a .spiderbrain/ folder, point the reader at it:

npx spiderbrain mcp --root .

An MCP client's working directory is usually not your repository, so pass the repo explicitly with --root <path>, --root=<path>, or the SPIDERBRAIN_ROOT environment variable. Without it the server serves the working directory and reports that no understanding layer was found, which is a wrong answer rather than an error.

That starts an MCP server your coding agent (Claude Code, Cursor, or any MCP client) can query. Tools: sb_blast, sb_impact, sb_path, sb_keystones, sb_map, sb_ask. No account, no SpiderBrain install, no configuration. A real session transcript is in examples/agent-session.md.

Prefer the terminal:

npx spiderbrain blast src/server/health.ts   # what a change here reaches
npx spiderbrain impact                        # what YOUR CURRENT DIFF reaches
npx spiderbrain keystones                     # the load-bearing files
npx spiderbrain map src/auth/session.ts       # what a file is + touches
npx spiderbrain path src/a.ts src/b.ts        # how one file reaches another
npx spiderbrain verify --allow-stale          # folder untampered? see note below

Why --allow-stale on a committed brain. verify checks two things: that structure.ndjson still matches its recorded fingerprint, and that the brain was scored at the current HEAD. Committing the folder is itself a commit, so a brain committed to a repo is always at least one commit behind and the second check can never pass on a fresh clone. --allow-stale keeps the integrity check strict and tolerates only that. Drop the flag when you build the brain in CI at the commit you are testing, where currency is real.

Agents are first-class

Every command takes --json and emits one machine-readable object, and exit codes are part of the contract: 0 ok, 1 check failed, 2 usage, 3 no understanding. CI can gate on them:

npx spiderbrain impact --fail-over 200   # fail a PR whose blast exceeds 200 files
npx spiderbrain verify                   # fail a build whose folder is stale or edited (drop --allow-stale to require currency)

Ready-made workflows - a PR blast-radius comment and a freshness gate - are in examples/.

No folder? Registry fallback

When a repo carries no .spiderbrain/ folder, the reader checks the public SpiderBrain registry for an unofficial brain of the same repo (matched by the origin remote, clearly labeled, fingerprint-verified). The committed folder always wins when present; maintainers can publish the official one with npx spiderbrain create.

This repo eats its own dogfood

This repository carries its own committed .spiderbrain/ folder, derived from its real import graph (node scripts/build-own-brain.mjs, regenerated deterministically, verified in CI). Clone it and ask it about itself:

npx spiderbrain keystones      # read/src/core.mjs is the load-bearing file
npx spiderbrain verify --allow-stale   # the committed fingerprint matches the bytes

Give your own repo understanding

export SPIDERBRAIN_API_KEY=sb_live_...     # https://spiderbrain.ai/dashboard?tab=keys
npx spiderbrain create

Fetches your scored brain and writes the source-free .spiderbrain/ folder plus an AGENTS.md block. Commit both, and every agent that later touches the repo reads it.

Offline vs cloud

• Offline (free, deterministic, from the committed bytes): structure, dependencies, blast radius, keystones. Same repo, same question, same answer, byte for byte.
• Cloud (set SPIDERBRAIN_API_KEY): the why behind a file (the recorded decision and its reasoning), always-fresh scores, and semantic search. Get a key at https://spiderbrain.ai/dashboard?tab=keys.

export SPIDERBRAIN_API_KEY=sb_live_...
npx spiderbrain why src/billing/charge.ts

What is in the folder

The committed .spiderbrain/ folder is source-free: file paths, structure, and an edge-derivable blast radius only. Never your source code. Never the scoring weights. Its exact contents and determinism guarantees are documented in SPEC.md.

Every folder carries a fingerprint in its manifest.json; the reader recomputes it on load, so a hand-edited or corrupted folder is flagged and the map you query is the map that was published.

This repo (three MIT packages + the spec)

• spiderbrain/ — spiderbrain, the one command. A thin dispatcher over the two below.
• read/ — @spiderbrain/read, consume: folder loader, blast-radius traversal, CLI, MCP server, cloud client. Zero dependencies.
• create/ — @spiderbrain/create, produce: fetch your scored brain and write the understanding set + AGENTS.md.
• SPEC.md — the .spiderbrain/ public folder format.

Each scoped package is independently installable: a CI job that only publishes understanding needs @spiderbrain/create alone; an MCP config that only reads points at @spiderbrain/read. spiderbrain is what you type when you just want the thing.

The engine that scores a brain (parsing and the scoring model) is proprietary and lives with SpiderBrain. What is open here is the format, the reader, and the producer client, so anyone can read or write a published understanding layer, or build a tool that does.

License

MIT. See LICENSE.