SpiderBrain: la capa de comprensión para tu repositorio

Un repositorio le dice a un agente de IA qué es el código. Nunca le dice qué es lo que importa, a qué llega un cambio, ni por qué se construyó algo de la manera en que se hizo. Así que cada agente vuelve a derivar la estructura desde cero, en cada sesión, y se equivoca un poco.

SpiderBrain le da a un repositorio una capa de comprensión confirmada y sin código fuente: un mapa determinista de su estructura, dependencias y radio de impacto que cualquier agente de IA de codificación puede leer sin configuración alguna. Este repositorio es la parte abierta, con licencia MIT, de esa capa: el lector y la especificación del formato.

• Sitio web: https://spiderbrain.ai

• Punto de referencia de determinismo: https://contextbenchmark.com

Úsalo en una línea

Cuando un repositorio lleva una carpeta .spiderbrain/, apunta el lector hacia ella:

npx spiderbrain mcp --root .

El directorio de trabajo de un cliente MCP normalmente no es tu repositorio, así que pasa el repositorio explícitamente con --root <path>, --root=<path> o la variable de entorno SPIDERBRAIN_ROOT. Sin ello, el servidor sirve el directorio de trabajo e informa de que no se encontró ninguna capa de comprensión, lo cual es una respuesta incorrecta más que un error.

Eso inicia un servidor MCP que tu agente de codificación (Claude Code, Cursor o cualquier cliente MCP) puede consultar. Herramientas: sb_blast, sb_impact, sb_path, sb_keystones, sb_map, sb_ask. Sin cuenta, sin instalar SpiderBrain, sin configuración. Hay una transcripción real de una sesión en examples/agent-session.md.

¿Prefieres la 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

Por qué --allow-stale en un cerebro confirmado. verify comprueba dos cosas: que structure.ndjson sigue coincidiendo con su huella registrada y que el cerebro se puntuó en el HEAD actual. Confirmar la carpeta es en sí mismo una confirmación, así que un cerebro confirmado en un repositorio siempre está al menos una confirmación por detrás y la segunda comprobación nunca puede pasar en un clon nuevo. --allow-stale mantiene estricta la comprobación de integridad y solo tolera eso. Omite la bandera cuando compiles el cerebro en CI en la confirmación que estás probando, donde la actualidad es real.

Related MCP server: mcp-codebase-intelligence

Los agentes son de primera clase

Cada comando acepta --json y emite un objeto legible por máquina, y los códigos de salida forman parte del contrato: 0 correcto, 1 comprobación fallida, 2 uso, 3 sin comprensión. El CI puede usarlos como puerta de verificación:

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)

Hay flujos de trabajo listos para usar (un comentario de radio de impacto en PR y una puerta de frescura) en examples/.

¿Sin carpeta? Respaldo del registro

Cuando un repositorio no lleva una carpeta .spiderbrain/, el lector consulta el registro público de SpiderBrain en busca de un cerebro no oficial del mismo repositorio (coincidiendo con el remoto origin, claramente etiquetado y verificado por huella). La carpeta confirmada siempre gana cuando está presente; los mantenedores pueden publicar la oficial con npx spiderbrain create.

Este repositorio practica su propia medicina

Este repositorio incluye su propia carpeta .spiderbrain/ confirmada, derivada de su grafo de importación real (node scripts/build-own-brain.mjs, regenerada de forma determinista y verificada en CI). Clónalo y pregúntale sobre sí mismo:

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

Dale comprensión a tu propio repositorio

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

Obtiene tu cerebro puntuado y escribe la carpeta .spiderbrain/ sin código fuente junto con un bloque AGENTS.md. Confirma ambos, y todo agente que toque el repositorio después los leerá.

Sin conexión frente a la nube

• Sin conexión (gratuito, determinista, a partir de los bytes confirmados): estructura, dependencias, radio de impacto, piedras angulares. Mismo repositorio, misma pregunta, misma respuesta, byte por byte.

• Nube (establece SPIDERBRAIN_API_KEY): el porqué detrás de un archivo (la decisión registrada y su razonamiento), puntuaciones siempre actualizadas y búsqueda semántica. Consigue una clave en https://spiderbrain.ai/dashboard?tab=keys.

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

Qué hay en la carpeta

La carpeta .spiderbrain/ confirmada no contiene código fuente: solo rutas de archivo, estructura y un radio de impacto derivable por aristas. Nunca tu código fuente. Nunca los pesos de puntuación. Su contenido exacto y las garantías de determinismo están documentados en SPEC.md.

Cada carpeta lleva una huella en su manifest.json; el lector la recalcula al cargarla, de modo que una carpeta editada a mano o corrupta se marca y el mapa que consultas es el que se publicó.

Este repositorio (tres paquetes MIT + la especificación)

• spiderbrain/ — spiderbrain, el único comando. Un despachador fino sobre los dos siguientes.

• read/ — @spiderbrain/read, consume: cargador de carpetas, recorrido de radio de impacto, CLI, servidor MCP, cliente en la nube. Cero dependencias.

• create/ — @spiderbrain/create, produce: obtén tu cerebro puntuado y escribe el conjunto de comprensión + AGENTS.md.

• SPEC.md — el formato público de la carpeta .spiderbrain/.

Cada paquete con ámbito se puede instalar de forma independiente: un trabajo de CI que solo publica comprensión necesita únicamente @spiderbrain/create; una configuración MCP que solo lee apunta a @spiderbrain/read. spiderbrain es lo que escribes cuando solo quieres la herramienta.

El motor que puntúa un cerebro (análisis sintáctico y modelo de puntuación) es propietario y pertenece a SpiderBrain. Lo que aquí es abierto es el formato, el lector y el cliente productor, para que cualquiera pueda leer o escribir una capa de comprensión publicada, o crear una herramienta que lo haga.

Licencia

MIT. Consulta LICENSE.