CodeBrain

Un servidor MCP que permite a Claude Code descargar trabajo masivo a un LLM local ejecutándose en tu propio hardware.

Qué es (y qué no es)

Es: Un servidor del Protocolo de Contexto de Modelos (MCP) que Claude Code registra como un backend de sub-agente. Cuando una sesión incluye el tipo de tarea que un modelo de programación local de 14B maneja bien —generar 50 plantillas de eventos, pulir 20 componentes de React, redactar código repetitivo—, Claude Code llama a CodeBrain en lugar de gastar sus propios tokens de salida. El modelo local hace el borrador masivo, Claude revisa y aplica.

No es: Un reemplazo de Claude. El razonamiento, las decisiones de arquitectura, la depuración y cualquier cosa donde "suficientemente bueno" no sea suficiente se queda con Claude. CodeBrain es un descargador de Claude, no un competidor de Claude.

Por qué: El trabajo de pulido y contenido de gran volumen consume rápidamente el contexto y los límites de tasa de Claude. Un modelo local que puedes ejecutar de forma ilimitada no cuesta nada extra por llamada y mantiene el contexto de alto valor libre para las partes difíciles de la sesión.

Related MCP server: ollama-mcp

Estado

Fases 1–4 completadas, Fase 5 pospuesta. Nueve herramientas expuestas, paso a través de .brain/context.md activo, escáner de resúmenes de cerebro por archivo, bucle de verificación, decodificación por consenso. Integración MCP verificada en una sesión real de Claude Code. La Fase 5 (RAG) se definió explícitamente como "solo si es necesario" y el uso actual no muestra que la búsqueda entre archivos sea un cuello de botella, por lo que permanece pospuesta.

Cómo funciona

Claude Code session                     CodeBrain MCP server              Local machine
─────────────────────      stdio       ───────────────────                ─────────────
Claude delegates a         ────────►   codebrain_generate()     ────►    Ollama HTTP
bulk / polish task                     codebrain_explain()                (localhost:11434)
                                       codebrain_status()                      │
                                                                                ▼
                                                                        Qwen2.5-Coder 14B
                                                                              (GPU)
Claude reviews,            ◄────────   tool result string        ◄────    streamed response
applies, or pushes back

Nueve herramientas están expuestas hoy:

El flag use_brain en las herramientas de generación antepone automáticamente .brain/context.md del directorio de trabajo actual al prompt del sistema, por lo que el contexto específico del proyecto viaja con cada llamada sin que Claude tenga que pasarlo manualmente.

Requisitos

• Python 3.11+

• Ollama — descargar para tu SO. Probado con Ollama en Windows nativo, comunicándose a través de localhost:1434.

• Un modelo de programación descargado localmente:

  ollama pull qwen2.5-coder:14b

  Descarga de ~9 GB. Cabe en 12 GB de VRAM en Q5. Otros modelos también funcionan (DeepSeek-Coder, Qwen3 si está disponible) — configúralo mediante la variable de entorno CODEBRAIN_MODEL.

• Claude Code CLI en la máquina que llamará al servidor (obviamente).

Instalación

git clone <this repo> CodeBrain
cd CodeBrain
python -m venv .venv
.venv\Scripts\activate                         # on Windows
# source .venv/bin/activate                    # on macOS / Linux
pip install -e .

Configurar Claude Code

Añade CodeBrain a tu configuración MCP de Claude Code. En Windows, eso suele ser ~/.claude.json (ajusta la ruta a donde clonaste):

{
  "mcpServers": {
    "codebrain": {
      "command": "C:\\Users\\YOU\\Desktop\\CodeBrain\\.venv\\Scripts\\python.exe",
      "args": ["-m", "codebrain"]
    }
  }
}

Reinicia cualquier sesión de Claude Code: las cinco herramientas codebrain_* deberían aparecer ahora en la lista de herramientas disponibles.

Mantén los archivos brain sincronizados automáticamente

Una vez que hayas ejecutado codebrain_init en un repositorio y lo hayas escaneado con codebrain_scan_repo, probablemente querrás que los archivos brain se actualicen automáticamente cada vez que Claude edite el código fuente. Dos piezas conectan esto:

1. Fragmento de CLAUDE.md del proyecto — dile a Claude que lea los archivos brain antes de abrir el código fuente:

## Brain files

This repo has per-file `.brain` summaries next to each source file.
Before reading a full source file, read its `<path>.brain` sibling first.
Only open the source when the brain file is insufficient for the task.

2. Hook PostToolUse — regenera el cerebro después de cada Edit/Write.

Añádelo a .claude/settings.json en la raíz del repositorio:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python -c \"import asyncio, json, sys; from codebrain.brain_scanner import scan_file; d = json.load(sys.stdin); p = d.get('tool_input', {}).get('file_path'); p and p.endswith(('.py', '.ts', '.tsx', '.js', '.jsx', '.java', '.go', '.rs')) and print(asyncio.run(scan_file(p)))\""
          }
        ]
      }
    ]
  }
}

El hook inspecciona la ruta editada, omite archivos que no son código fuente mediante el filtro de extensión y lanza un escaneo. Protegido por hash: los archivos sin cambios no tocan Qwen.

Verificación de cordura

Dentro de una sesión de Claude Code, pregúntale a Claude:

Llama a codebrain_status y dime qué hay instalado.

Si Ollama se está ejecutando y el modelo está descargado, obtendrás qwen2.5-coder:14b en la lista.

Configuración

Variables de entorno leídas por el backend:

Estructura del proyecto

CodeBrain/
├── codebrain/
│   ├── __init__.py
│   ├── __main__.py            # `python -m codebrain` entry
│   ├── backend.py             # Ollama HTTP client
│   ├── server.py              # FastMCP server + tool definitions
│   ├── brain_scanner.py       # scan_file / scan_repo + hash gate
│   ├── brain_init.py          # one-shot .brain/context.md seeding
│   ├── verifier.py            # deterministic output checks
│   └── prompts/
│       └── brain_few_shot.md  # few-shot for brain-file generation
├── tests/                     # 96 unit + integration tests
├── .spec/
│   ├── CURRENT.md             # phase state
│   └── brain-file-format.md   # brain-file format v1
├── pyproject.toml
├── LICENSE
└── README.md

Hoja de ruta

Fase 1 — andamiaje ✓

• [x] Cliente HTTP de Ollama con manejo de errores

• [x] Servidor FastMCP con transporte stdio

• [x] Tres herramientas principales: generate, explain, status

• [x] Configuración documentada + configuración de Claude Code

• [x] Verificado en una sesión real de Claude Code

Fase 2 — lote y contexto ✓

• [x] codebrain_batch_generate para contenido masivo con un prompt de sistema compartido, errores estables por índice

• [x] codebrain_polish para transformaciones dirigidas (acortar / parafrasear / traducir) en lugar de regeneración

• [x] Paso a través de .brain/context.md — contexto del proyecto cwd antepuesto automáticamente a cada llamada de generación

• [x] Dogfood: tareas de programación sólidas, tareas de transformación de texto revelaron límites reales (informa la Fase 3)

Fase 2.5 — sistema brain ✓

Los resúmenes <source>.brain por archivo se sitúan junto a cada archivo fuente. Claude lee el cerebro primero y solo abre la fuente cuando el cerebro es insuficiente.

• [x] codebrain_scan_file(path, force) — generar o actualizar un archivo brain

• [x] codebrain_scan_repo(root, force, extensions, exclude_dirs) — recorrido masivo + escaneo

• [x] codebrain_init(root, force) — sembrar .brain/context.md con detección de stack

• [x] Regeneración protegida por hash (SHA256) — ejecuciones idempotentes

• [x] Frontmatter programático — source, source_hash, model deterministas; Qwen solo escribe las cinco secciones

• [x] Validación de defensa en profundidad: eliminación de vallas, omitir fuentes vacías (<10 caracteres), presencia/orden de secciones, reintento en caso de invalidez

• [x] Convención CLAUDE.md + fragmento de hook PostToolUse en este README

Fase 3 — bucle VERIFIER ✓

El dogfood mostró que el modelo local se desvía en las transformaciones de texto. El verificador detecta no-ops, violaciones de longitud y fallos de esquema de forma determinista antes de que lleguen a Claude.

• [x] detect_noop — comprobación de igualdad normalizada por espacios en blanco (reintento automático dentro de codebrain_polish)

• [x] check_word_count(min_words, max_words) — puerta de ventana acotada

• [x] check_regex_schema(pattern) — comprobación de salida estructurada

• [x] codebrain_generate_verified(prompt, min_words, max_words, must_match, max_retries) — bucle con instrucciones de reintento ajustadas, devuelve [codebrain warning] ... si la verificación falla después de los reintentos

Fase 4 — decodificación por consenso ✓

• [x] codebrain_consensus_generate(prompt, n) — generar N candidatos (limitado a [2,5]), Qwen elige el mejor literalmente. N+1 llamadas de inferencia, ajusta la calidad en tareas de alta varianza.

• Esqueleto de múltiples pasadas→lógica→bordes→pulido: pospuesto (bajo valor medido; las herramientas individuales ya se componen).

Fase 5 — RAG (pospuesto — no es un cuello de botella)

Los archivos brain ya actúan como un índice; el RAG entre archivos solo tiene sentido si el uso futuro realmente muestra que la indexación es el bloqueador. No hay señal actual para ello, así que no se ha construido.

Licencia

MIT — ver LICENSE.