CodeBrain

Claude Codeが、自身のハードウェアで実行されているローカルLLMに大量の作業をオフロードできるようにするMCPサーバーです。

これは何なのか（何ではないのか）

何なのか: Claude Codeがサブエージェントのバックエンドとして登録するModel Context Protocol (MCP) サーバーです。14Bクラスのローカルコーダーモデルが得意とするタスク（イベントテンプレートの50個生成、Reactコンポーネント20個の推敲、ボイラープレートの作成など）が含まれるセッションにおいて、Claude Codeは自身の出力トークンを消費する代わりにCodeBrainを呼び出します。ローカルモデルがドラフトを作成し、Claudeがそれをレビューして適用します。

何ではないのか: Claudeの代替品ではありません。推論、アーキテクチャの決定、デバッグ、そして「そこそこ」では不十分なあらゆる作業はClaudeが担当します。CodeBrainはClaudeのオフローダーであり、Claudeの競合相手ではありません。

なぜ必要なのか: 大量のコンテンツ作成や推敲作業は、Claudeのコンテキストとレート制限を急速に消費します。無制限に実行できるローカルモデルは呼び出しごとの追加コストがかからず、セッションの重要な部分のためにClaudeの貴重なコンテキストを温存できます。

Related MCP server: ollama-mcp

ステータス

フェーズ1〜4完了、フェーズ5は延期。 9つのツールを公開済み。.brain/context.mdのパススルー機能、ファイルごとのBrain要約スキャナー、検証ループ、コンセンサスデコーディングが実装されています。MCP統合は実際のClaude Codeセッションで検証済みです。フェーズ5（RAG）は「必要な場合のみ」と定義されていましたが、現在の使用状況ではファイル横断検索がボトルネックになっていないため、延期とします。

仕組み

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

現在、9つのツールが公開されています：

生成ツールにあるuse_brainフラグは、現在の作業ディレクトリにある.brain/context.mdをシステムプロンプトの先頭に自動的に追加します。これにより、Claudeが手動で渡さなくても、プロジェクト固有のコンテキストがすべての呼び出しに引き継がれます。

要件

• Python 3.11+

• Ollama — OS用をダウンロード。Windowsネイティブでlocalhost:11434経由の通信でテスト済み。

• ローカルにプルされたコーダーモデル:

  ollama pull qwen2.5-coder:14b

  約9GBのダウンロード。Q5設定で12GBのVRAMに収まります。他のモデル（DeepSeek-Coder、利用可能な場合はQwen3など）も動作します。CODEBRAIN_MODEL環境変数で設定してください。

• Claude Code CLI（サーバーを呼び出すマシン上）。

インストール

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の設定

Claude CodeのMCP設定にCodeBrainを追加します。Windowsの場合、通常は~/.claude.jsonです（パスはクローンした場所に合わせて調整してください）：

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

Claude Codeセッションを再起動すると、5つのcodebrain_*ツールが利用可能なツールリストに表示されるはずです。

Brainファイルを自動的に同期する

リポジトリでcodebrain_initを実行し、codebrain_scan_repoでスキャンした後、Claudeがソースを編集するたびにBrainファイルを自動的に更新したい場合があるでしょう。以下の2つを設定します：

1. プロジェクトのCLAUDE.mdスニペット — ソースを開く前にBrainファイルを読み込むようClaudeに指示します：

## 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フック — 編集/書き込みのたびにBrainを再生成します。

リポジトリルートの.claude/settings.jsonに追加します：

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

このフックは編集されたパスを検査し、拡張子フィルターでソース以外のファイルをスキップしてスキャンを開始します。ハッシュ管理されているため、変更されていないファイルはQwenに送信されません。

動作確認

Claude Codeセッション内で、Claudeに次のように尋ねます：

codebrain_statusを呼び出して、何がインストールされているか教えて。

Ollamaが実行中でモデルがプルされていれば、リストにqwen2.5-coder:14bが表示されます。

設定

バックエンドが読み取る環境変数：

プロジェクト構造

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

ロードマップ

フェーズ1 — スキャフォールド ✓

• [x] エラーハンドリング付きOllama HTTPクライアント

• [x] stdioトランスポートを備えたFastMCPサーバー

• [x] 3つのコアツール: generate, explain, status

• [x] ドキュメント化されたセットアップ + Claude Code設定

• [x] 実際のClaude Codeセッションでの検証

フェーズ2 — バッチとコンテキスト ✓

• [x] 共通のシステムプロンプトを用いた大量コンテンツ生成用のcodebrain_batch_generate、インデックス安定エラー

• [x] 再生成ではなくターゲット変換（短縮/言い換え/翻訳）を行うcodebrain_polish

• [x] .brain/context.mdパススルー — すべての生成呼び出しにcwdプロジェクトコンテキストを自動付与

• [x] ドッグフーディング: コーディングタスクは堅牢、テキスト変換タスクで真の限界が判明（フェーズ3に反映）

フェーズ2.5 — Brainシステム ✓

ファイルごとの<source>.brain要約が各ソースファイルの隣に配置されます。ClaudeはまずBrainを読み、Brainで不十分な場合にのみソースを開きます。

• [x] codebrain_scan_file(path, force) — 1つのBrainファイルを生成または更新

• [x] codebrain_scan_repo(root, force, extensions, exclude_dirs) — 一括走査 + スキャン

• [x] codebrain_init(root, force) — スタック検出付きで.brain/context.mdをシード

• [x] ハッシュ管理された再生成 (SHA256) — 冪等な再実行

• [x] プログラムによるフロントマター — 決定論的なsource, source_hash, model; Qwenは5つのセクションのみを記述

• [x] 多層防御バリデーション: フェンス除去、空ソースのスキップ（10文字未満）、セクションの存在/順序、無効時の再試行

• [x] CLAUDE.md規約 + このREADME内のPostToolUseフックスニペット

フェーズ3 — VERIFIERループ ✓

ドッグフーディングにより、ローカルモデルがテキスト変換でドリフトすることが判明しました。検証機能は、Claudeに到達する前に、ノーオペレーション、長さ違反、スキーマ不一致を決定論的にキャッチします。

• [x] detect_noop — 空白を正規化した等価性チェック（codebrain_polish内で自動再試行）

• [x] check_word_count(min_words, max_words) — 境界ウィンドウゲート

• [x] check_regex_schema(pattern) — 構造化出力チェック

• [x] codebrain_generate_verified(prompt, min_words, max_words, must_match, max_retries) — 強化された再試行指示を伴うループ。検証失敗時は[codebrain warning] ...を返す

フェーズ4 — コンセンサスデコーディング ✓

• [x] codebrain_consensus_generate(prompt, n) — N個の候補を生成（[2,5]に制限）、Qwenが最適なものを逐語的に選択。N+1回の推論呼び出しにより、分散の大きいタスクの品質を向上。

• マルチパス（スケルトン→ロジック→エッジ→推敲）: 延期（測定値が低く、個々のツールで既に構成可能なため）。

フェーズ5 — RAG (延期 — ボトルネックではないため)

Brainファイルが既にインデックスとして機能しています。ファイル横断RAGは、将来的にインデックス作成がボトルネックであると判明した場合にのみ意味を持ちます。現在のところその兆候はないため、構築していません。

ライセンス

MIT — LICENSEを参照。