{
  "markdown": "# SpiderBrain: the understanding layer for your repo\n\n[![conformance](https://github.com/aabhisrv/Spiderbrain.ai-Coremind/actions/workflows/ci.yml/badge.svg)](https://github.com/aabhisrv/Spiderbrain.ai-Coremind/actions/workflows/ci.yml)\n\nA repo tells an AI agent *what* the code is. It never tells it what **matters**, what a\nchange **reaches**, or **why** anything was built the way it was. So every agent\nre-derives the structure from scratch, every session, and gets it a little wrong.\n\nSpiderBrain gives a repo a committed, source-free understanding layer: a deterministic\nmap of its structure, dependencies, and blast radius that any AI coding agent can read\nwith zero setup. This repository is the open, MIT-licensed part of that layer: the\nreader, and the format specification.\n\n- Website: https://spiderbrain.ai\n- Determinism benchmark: https://contextbenchmark.com\n\n## Use it in one line\n\nWhen a repo carries a `.spiderbrain/` folder, point the reader at it:\n\n```\nnpx spiderbrain mcp --root .\n```\n\n> An MCP client's working directory is usually not your repository, so pass the repo\n> explicitly with `--root <path>`, `--root=<path>`, or the `SPIDERBRAIN_ROOT` environment\n> variable. Without it the server serves the working directory and reports that no\n> understanding layer was found, which is a wrong answer rather than an error.\n\nThat starts an MCP server your coding agent (Claude Code, Cursor, or any MCP client)\ncan query. Tools: `sb_blast`, `sb_impact`, `sb_path`, `sb_keystones`, `sb_map`,\n`sb_ask`. No account, no SpiderBrain install, no configuration. A real session\ntranscript is in [examples/agent-session.md](examples/agent-session.md).\n\nPrefer the terminal:\n\n```\nnpx spiderbrain blast src/server/health.ts   # what a change here reaches\nnpx spiderbrain impact                        # what YOUR CURRENT DIFF reaches\nnpx spiderbrain keystones                     # the load-bearing files\nnpx spiderbrain map src/auth/session.ts       # what a file is + touches\nnpx spiderbrain path src/a.ts src/b.ts        # how one file reaches another\nnpx spiderbrain verify --allow-stale          # folder untampered? see note below\n```\n\n> **Why `--allow-stale` on a committed brain.** `verify` checks two things: that\n> `structure.ndjson` still matches its recorded fingerprint, and that the brain was scored at\n> the current `HEAD`. Committing the folder is itself a commit, so a brain committed to a repo\n> is always at least one commit behind and the second check can never pass on a fresh clone.\n> `--allow-stale` keeps the integrity check strict and tolerates only that. Drop the flag when\n> you build the brain in CI at the commit you are testing, where currency is real.\n\n## Agents are first-class\n\nEvery command takes `--json` and emits one machine-readable object, and exit codes\nare part of the contract: `0` ok, `1` check failed, `2` usage, `3` no understanding.\nCI can gate on them:\n\n```\nnpx spiderbrain impact --fail-over 200   # fail a PR whose blast exceeds 200 files\nnpx spiderbrain verify                   # fail a build whose folder is stale or edited (drop --allow-stale to require currency)\n```\n\nReady-made workflows - a PR blast-radius comment and a freshness gate - are in\n[examples/](examples).\n\n## No folder? Registry fallback\n\nWhen a repo carries no `.spiderbrain/` folder, the reader checks the public\nSpiderBrain registry for an **unofficial** brain of the same repo (matched by the\n`origin` remote, clearly labeled, fingerprint-verified). The committed folder always\nwins when present; maintainers can publish the official one with `npx spiderbrain create`.\n\n## This repo eats its own dogfood\n\nThis repository carries its own committed [`.spiderbrain/`](.spiderbrain) folder,\nderived from its real import graph (`node scripts/build-own-brain.mjs`, regenerated\ndeterministically, verified in CI). Clone it and ask it about itself:\n\n```\nnpx spiderbrain keystones      # read/src/core.mjs is the load-bearing file\nnpx spiderbrain verify --allow-stale   # the committed fingerprint matches the bytes\n```\n\n## Give your own repo understanding\n\n```\nexport SPIDERBRAIN_API_KEY=sb_live_...     # https://spiderbrain.ai/dashboard?tab=keys\nnpx spiderbrain create\n```\n\nFetches your scored brain and writes the source-free `.spiderbrain/` folder plus an\n`AGENTS.md` block. Commit both, and every agent that later touches the repo reads it.\n\n## Offline vs cloud\n\n- **Offline** (free, deterministic, from the committed bytes): structure, dependencies,\n  blast radius, keystones. Same repo, same question, same answer, byte for byte.\n- **Cloud** (set `SPIDERBRAIN_API_KEY`): the *why* behind a file (the recorded decision\n  and its reasoning), always-fresh scores, and semantic search. Get a key at\n  https://spiderbrain.ai/dashboard?tab=keys.\n\n```\nexport SPIDERBRAIN_API_KEY=sb_live_...\nnpx spiderbrain why src/billing/charge.ts\n```\n\n## What is in the folder\n\nThe committed `.spiderbrain/` folder is **source-free**: file paths, structure, and an\nedge-derivable blast radius only. Never your source code. Never the scoring weights.\nIts exact contents and determinism guarantees are documented in [SPEC.md](SPEC.md).\n\nEvery folder carries a fingerprint in its `manifest.json`; the reader recomputes it on\nload, so a hand-edited or corrupted folder is flagged and the map you query is the map\nthat was published.\n\n## This repo (three MIT packages + the spec)\n\n- [`spiderbrain/`](spiderbrain) — [`spiderbrain`](https://www.npmjs.com/package/spiderbrain),\n  the one command. A thin dispatcher over the two below.\n- [`read/`](read) — [`@spiderbrain/read`](https://www.npmjs.com/package/@spiderbrain/read),\n  **consume**: folder loader, blast-radius traversal, CLI, MCP server, cloud client. Zero\n  dependencies.\n- [`create/`](create) — [`@spiderbrain/create`](https://www.npmjs.com/package/@spiderbrain/create),\n  **produce**: fetch your scored brain and write the understanding set + `AGENTS.md`.\n- [`SPEC.md`](SPEC.md) — the `.spiderbrain/` public folder format.\n\nEach scoped package is independently installable: a CI job that only publishes understanding\nneeds `@spiderbrain/create` alone; an MCP config that only reads points at `@spiderbrain/read`.\n`spiderbrain` is what you type when you just want the thing.\n\nThe engine that *scores* a brain (parsing and the scoring model) is proprietary and lives\nwith SpiderBrain. What is open here is the **format**, the **reader**, and the **producer\nclient**, so anyone can read or write a published understanding layer, or build a tool that\ndoes.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 6559,
  "sha": "0b29412b0c77518e9c7ec0ff0f6465dbb751a2859e2e1314a0578d4c672e36d2",
  "repo_slug": "aabhisrv/spiderbrain.ai-coremind",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_spiderbrain_spiderbrain_dc8c7abc/readme"
}