SpiderBrain: die Verständnisschicht für dein Repository

Ein Repository sagt einem KI-Agenten was der Code ist. Es sagt ihm nie, was wichtig ist, was eine Änderung erreicht oder warum etwas so gebaut wurde, wie es gebaut wurde. Also leitet jeder Agent die Struktur bei jeder Sitzung von Grund auf neu ab und bekommt sie ein wenig falsch hin.

SpiderBrain gibt einem Repository eine festgeschriebene, quellfreie Verständnisschicht: eine deterministische Karte seiner Struktur, Abhängigkeiten und seines Blast-Radius, die jeder KI-Code-Agent ohne Einrichtung lesen kann. Dieses Repository ist der offene, MIT-lizenzierte Teil dieser Schicht: der Leser und die Formatspezifikation.

• Website: https://spiderbrain.ai

• Determinismus-Benchmark: https://contextbenchmark.com

Verwendung in einer Zeile

Wenn ein Repository einen .spiderbrain/-Ordner enthält, weise den Leser darauf hin:

npx spiderbrain mcp --root .

Das Arbeitsverzeichnis eines MCP-Clients ist normalerweise nicht dein Repository, also übergib das Repository explizit mit --root <path>, --root=<path> oder der Umgebungsvariable SPIDERBRAIN_ROOT. Ohne diese bedient der Server das Arbeitsverzeichnis und meldet, dass keine Verständnisschicht gefunden wurde – das ist eine falsche Antwort und kein Fehler.

Das startet einen MCP-Server, den dein Code-Agent (Claude Code, Cursor oder ein beliebiger MCP-Client) abfragen kann. Werkzeuge: sb_blast, sb_impact, sb_path, sb_keystones, sb_map, sb_ask. Kein Konto, keine SpiderBrain-Installation, keine Konfiguration. Ein echtes Sitzungsprotokoll findest du in examples/agent-session.md.

Bevorzugst du das 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

Warum --allow-stale bei einem festgeschriebenen Brain. verify prüft zwei Dinge: dass structure.ndjson immer noch mit seinem aufgezeichneten Fingerabdruck übereinstimmt und dass das Brain am aktuellen HEAD bewertet wurde. Das Festschreiben des Ordners ist selbst ein Commit, also ist ein in einem Repository festgeschriebenes Brain immer mindestens einen Commit zurück und die zweite Prüfung kann bei einem frischen Klon nie bestehen. --allow-stale hält die Integritätsprüfung streng und toleriert nur das. Entferne das Flag, wenn du das Brain in CI bei dem Commit erstellst, den du testest, wo Aktualität real ist.

Related MCP server: mcp-codebase-intelligence

Agenten sind erstklassig

Jeder Befehl akzeptiert --json und gibt ein maschinenlesbares Objekt aus, und Exit-Codes sind Teil des Vertrags: 0 ok, 1 Prüfung fehlgeschlagen, 2 Verwendung, 3 keine Verständnisschicht. CI kann darauf aufbauen:

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)

Fertige Workflows – ein PR-Blast-Radius-Kommentar und ein Frische-Gate – findest du in examples/.

Kein Ordner? Registry-Fallback

Wenn ein Repository keinen .spiderbrain/-Ordner enthält, prüft der Leser die öffentliche SpiderBrain-Registry auf ein inoffizielles Brain desselben Repositorys (abgeglichen über den origin-Remote, klar gekennzeichnet, fingerabdruck-verifiziert). Der festgeschriebene Ordner gewinnt immer, wenn er vorhanden ist; Maintainer können das offizielle mit npx spiderbrain create veröffentlichen.

Dieses Repository isst sein eigenes Hundefutter

Dieses Repository enthält seinen eigenen festgeschriebenen .spiderbrain/-Ordner, abgeleitet aus seinem echten Importgraphen (node scripts/build-own-brain.mjs, deterministisch regeneriert, in CI verifiziert). Klone es und frage es nach sich selbst:

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

Gib deinem eigenen Repository Verständnis

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

Holt dein bewertetes Brain und schreibt den quellfreien .spiderbrain/-Ordner plus einen AGENTS.md-Block. Committe beides, und jeder Agent, der später das Repository berührt, liest es.

Offline vs. Cloud

• Offline (kostenlos, deterministisch, aus den festgeschriebenen Bytes): Struktur, Abhängigkeiten, Blast-Radius, Kernmodule. Gleiches Repository, gleiche Frage, gleiche Antwort, Byte für Byte.

• Cloud (setze SPIDERBRAIN_API_KEY): das Warum hinter einer Datei (die aufgezeichnete Entscheidung und ihre Begründung), immer aktuelle Bewertungen und semantische Suche. Hol dir einen Schlüssel unter https://spiderbrain.ai/dashboard?tab=keys.

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

Was im Ordner ist

Der festgeschriebene .spiderbrain/-Ordner ist quellfrei: nur Dateipfade, Struktur und ein aus Kanten ableitbarer Blast-Radius. Niemals dein Quellcode. Niemals die Bewertungsgewichte. Sein genauer Inhalt und die Determinismus-Garantien sind in SPEC.md dokumentiert.

Jeder Ordner trägt einen Fingerabdruck in seiner manifest.json; der Leser berechnet ihn beim Laden neu, sodass ein manuell bearbeiteter oder beschädigter Ordner markiert wird und die Karte, die du abfragst, die Karte ist, die veröffentlicht wurde.

Dieses Repository (drei MIT-Pakete + die Spezifikation)

• spiderbrain/ — spiderbrain, der eine Befehl. Ein dünner Dispatcher über die beiden folgenden.

• read/ — @spiderbrain/read, konsumieren: Ordner-Loader, Blast-Radius-Traversal, CLI, MCP-Server, Cloud-Client. Null Abhängigkeiten.

• create/ — @spiderbrain/create, produzieren: Holt dein bewertetes Brain und schreibt das Verständnis-Set + AGENTS.md.

• SPEC.md — das öffentliche .spiderbrain/-Ordnerformat.

Jedes scoped Paket ist unabhängig installierbar: Ein CI-Job, der nur Verständnis veröffentlicht, braucht nur @spiderbrain/create; eine MCP-Konfiguration, die nur liest, zeigt auf @spiderbrain/read. spiderbrain ist das, was du tippst, wenn du einfach das Ding willst.

Die Engine, die ein Brain bewertet (Parsing und das Bewertungsmodell), ist proprietär und liegt bei SpiderBrain. Was hier offen ist, sind das Format, der Leser und der Produzenten-Client, sodass jeder eine veröffentlichte Verständnisschicht lesen oder schreiben oder ein Werkzeug bauen kann, das dies tut.

Lizenz

MIT. Siehe LICENSE.