CodeBrain

Ein MCP-Server, mit dem Claude Code umfangreiche Arbeiten an ein lokales LLM auslagern kann, das auf Ihrer eigenen Hardware läuft.

Was dies ist (und was nicht)

Ist: Ein Model Context Protocol (MCP)-Server, den Claude Code als Sub-Agent-Backend registriert. Wenn eine Sitzung die Art von Aufgabe enthält, die ein lokales 14B-Coder-Modell gut bewältigen kann — wie das Generieren von 50 Event-Templates, das Verfeinern von 20 React-Komponenten oder das Entwerfen von Boilerplate-Code —, ruft Claude Code CodeBrain auf, anstatt seine eigenen Output-Token zu verbrauchen.

Ist nicht: Ein Ersatz für Claude. Die logischen Überlegungen, Architektur-Entscheidungen, das Debugging und alles, bei dem "gut genug" nicht ausreicht, verbleiben bei Claude. CodeBrain ist ein Claude-Entlaster, kein Claude-Konkurrent.

Warum: Umfangreiche Inhalte und Verfeinerungsarbeiten verbrauchen Claudes Kontext und Ratenlimits schnell. Ein lokales Modell, das Sie unbegrenzt ausführen können, kostet pro Aufruf nichts extra und hält den wertvollen Kontext für die schwierigen Teile der Sitzung frei.

Related MCP server: ollama-mcp

Status

Phasen 1–4 abgeschlossen, Phase 5 zurückgestellt. Neun Tools verfügbar, .brain/context.md-Durchleitung aktiv, Scanner für dateispezifische Brain-Zusammenfassungen, Verifizierer-Schleife, Konsens-Dekodierung. Die MCP-Integration wurde in einer echten Claude Code-Sitzung verifiziert. Phase 5 (RAG) war explizit als "nur bei Bedarf" definiert, und die aktuelle Nutzung zeigt keine Engpässe bei der dateiübergreifenden Suche, daher bleibt sie zurückgestellt.

Funktionsweise

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

Derzeit sind neun Tools verfügbar:

Das use_brain-Flag bei Generierungs-Tools stellt automatisch .brain/context.md aus dem aktuellen Arbeitsverzeichnis vor den System-Prompt, sodass projektspezifischer Kontext bei jedem Aufruf mitgeführt wird, ohne dass Claude ihn manuell übergeben muss.

Anforderungen

• Python 3.11+

• Ollama — Download für Ihr Betriebssystem. Getestet mit Ollama unter Windows nativ, Kommunikation über localhost:11434.

• Ein lokal geladenes Coder-Modell:

  ollama pull qwen2.5-coder:14b

  ~9 GB Download. Passt bei Q5 in 12 GB VRAM. Andere Modelle funktionieren ebenfalls (DeepSeek-Coder, Qwen3 falls verfügbar) — Einstellung über die Umgebungsvariable CODEBRAIN_MODEL.

• Claude Code CLI auf der Maschine, die den Server aufruft (selbstverständlich).

Installation

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 .

Claude Code konfigurieren

Fügen Sie CodeBrain zu Ihrer Claude Code MCP-Konfiguration hinzu. Unter Windows ist das normalerweise ~/.claude.json (passen Sie den Pfad an den Ort an, an den Sie das Repository geklont haben):

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

Starten Sie jede Claude Code-Sitzung neu — die fünf codebrain_*-Tools sollten nun in der Liste der verfügbaren Tools erscheinen.

Brain-Dateien automatisch synchron halten

Sobald Sie codebrain_init in einem Repo ausgeführt und es mit codebrain_scan_repo gescannt haben, möchten Sie wahrscheinlich, dass die Brain-Dateien automatisch aktualisiert werden, wenn Claude Quellcode bearbeitet. Zwei Komponenten richten dies ein:

1. Projekt CLAUDE.md-Snippet — weisen Sie Claude an, Brain-Dateien zu lesen, bevor Quellcode geöffnet wird:

## 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. PostToolUse-Hook — regenerieren Sie das Brain nach jedem Edit/Write.

Fügen Sie dies in .claude/settings.json im Repo-Root hinzu:

{
  "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)))\""
          }
        ]
      }
    ]
  }
}

Der Hook untersucht den bearbeiteten Pfad, überspringt Nicht-Quellcodedateien über den Erweiterungsfilter und startet einen Scan. Hash-gesteuert: Unveränderte Dateien werden nicht an Qwen gesendet.

Plausibilitätsprüfung

Fragen Sie Claude innerhalb einer Claude Code-Sitzung:

Call codebrain_status and tell me what's installed.

Wenn Ollama läuft und das Modell geladen ist, erhalten Sie qwen2.5-coder:14b in der Liste zurück.

Konfiguration

Vom Backend gelesene Umgebungsvariablen:

Projektstruktur

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

Roadmap

Phase 1 — Grundgerüst ✓

• [x] Ollama HTTP-Client mit Fehlerbehandlung

• [x] FastMCP-Server mit stdio-Transport

• [x] Drei Kern-Tools: generate, explain, status

• [x] Dokumentiertes Setup + Claude Code-Konfiguration

• [x] Verifiziert in einer echten Claude Code-Sitzung

Phase 2 — Batch & Kontext ✓

• [x] codebrain_batch_generate für Masseninhalte mit einem gemeinsamen System-Prompt, indexstabile Fehler

• [x] codebrain_polish für gezielte Transformationen (kürzen / umformulieren / übersetzen) statt Neugenerierung

• [x] .brain/context.md-Durchleitung — CWD-Projektkontext wird automatisch vor jeden Generierungsaufruf gestellt

• [x] Dogfooding: Programmieraufgaben solide, Texttransformationsaufgaben zeigten echte Grenzen auf (informiert Phase 3)

Phase 2.5 — Brain-System ✓

Dateispezifische <source>.brain-Zusammenfassungen liegen neben jeder Quelldatei. Claude liest zuerst das Brain und öffnet die Quelle nur, wenn das Brain nicht ausreicht.

• [x] codebrain_scan_file(path, force) — eine Brain-Datei generieren oder aktualisieren

• [x] codebrain_scan_repo(root, force, extensions, exclude_dirs) — Massendurchlauf + Scan

• [x] codebrain_init(root, force) — .brain/context.md mit Stack-Erkennung initialisieren

• [x] Hash-gesteuerte Regeneration (SHA256) — idempotente Wiederholungen

• [x] Programmatisches Frontmatter — deterministisch source, source_hash, model; Qwen schreibt nur die fünf Abschnitte

• [x] Defense-in-Depth-Validierung: Fence-Strip, Überspringen leerer Quellen (<10 Zeichen), Abschnittspräsenz/-reihenfolge, Wiederholung bei Ungültigkeit

• [x] CLAUDE.md-Konvention + PostToolUse-Hook-Snippet in dieser README

Phase 3 — VERIFIER-Schleife ✓

Dogfooding zeigte, dass das lokale Modell bei Texttransformationen abweicht. Der Verifizierer erkennt No-Ops, Längenverletzungen und Schema-Fehler deterministisch, bevor sie Claude erreichen.

• [x] detect_noop — Whitespace-normalisierter Gleichheitscheck (automatische Wiederholung innerhalb von codebrain_polish)

• [x] check_word_count(min_words, max_words) — Schranke für Wortanzahl

• [x] check_regex_schema(pattern) — Prüfung auf strukturierten Output

• [x] codebrain_generate_verified(prompt, min_words, max_words, must_match, max_retries) — Schleife mit verschärften Wiederholungsanweisungen, gibt [codebrain warning] ... zurück, wenn die Verifizierung nach Wiederholungen fehlschlägt

Phase 4 — Konsens-Dekodierung ✓

• [x] codebrain_consensus_generate(prompt, n) — N Kandidaten generieren (begrenzt auf [2,5]), Qwen wählt das beste wörtlich aus. N+1 Inferenzaufrufe, erhöht die Qualität bei Aufgaben mit hoher Varianz.

• Multi-Pass Skelett→Logik→Kanten→Politur: zurückgestellt (geringer gemessener Wert; einzelne Tools lassen sich bereits kombinieren).

Phase 5 — RAG (zurückgestellt — kein Engpass)

Brain-Dateien fungieren bereits als Index; dateiübergreifendes RAG ist nur sinnvoll, wenn die zukünftige Nutzung tatsächlich zeigt, dass die Indizierung der Engpass ist. Aktuell gibt es dafür kein Signal, daher nicht implementiert.

Lizenz

MIT — siehe LICENSE.