Spiderbrain
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Open source Repository Open in the app JSON README (API)
About
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ai.spiderbrain
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.2.3
- Stars
- 3
- Last push
- 2026-08-21T12:33:14Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 03:00:41
- Updated
- 2026-08-29 03:00:41
- Origin id
ai.spiderbrain/spiderbrain
README
# SpiderBrain: the understanding layer for your repo [](https://github.com/aabhisrv/Spiderbrain.ai-Coremind/actions/workflows/ci.yml) 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](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/](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/`](.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](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) — [`spiderbrain`](https://www.npmjs.com/package/spiderbrain), the one command. A thin dispatcher over the two below. - [`read/`](read) — [`@spiderbrain/read`](https://www.npmjs.com/package/@spiderbrain/read), **consume**: folder loader, blast-radius traversal, CLI, MCP server, cloud client. Zero dependencies. - [`create/`](create) — [`@spiderbrain/create`](https://www.npmjs.com/package/@spiderbrain/create), **produce**: fetch your scored brain and write the understanding set + `AGENTS.md`. - [`SPEC.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](LICENSE).