SPIDERBRAIN_ROOT — Absolute path to the repository to serve, which must already contain a committed .spiderbrain/ folder. Set this: an MCP client's working directory is usually not your repository, and without it the server serves the working directory and reports that no understanding layer was found. Equivalent to passing --root.
SPIDERBRAIN_API_KEY — Optional. Enables the cloud why-layer used by the sb_ask tool. The structural tools work offline without it.
SPIDERBRAIN_REGISTRY — Optional. Base URL of the public brain registry this server consults on the first tool call when the repository has no committed .spiderbrain/ folder. Defaults to https://spiderbrain.ai/registry.
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.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
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.
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
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.
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.
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.