CodeBrain

一个 MCP 服务器，允许 Claude Code 将批量工作卸载到在你本地硬件上运行的本地 LLM。

这是什么（以及不是什么）

是： 一个模型上下文协议 (MCP) 服务器，Claude Code 将其注册为子代理后端。当会话包含 14B 本地编码模型擅长处理的任务（如生成 50 个事件模板、润色 20 个 React 组件、起草样板代码）时，Claude Code 会调用 CodeBrain，而不是消耗自己的输出 Token。本地模型负责完成草稿，Claude 负责审查和应用。

不是： Claude 的替代品。推理、架构决策、调试以及任何“差不多就行”无法满足要求的工作仍由 Claude 完成。CodeBrain 是一个 Claude 卸载器，而不是 Claude 的竞争对手。

原因： 大量的内容和润色工作会迅速消耗 Claude 的上下文和速率限制。你可以无限运行本地模型，每次调用无需额外成本，并能将高价值的上下文留给会话中的难点。

Related MCP server: ollama-mcp

状态

第 1-4 阶段已完成，第 5 阶段已推迟。 暴露了九个工具，.brain/context.md 透传功能已上线，支持逐文件大脑摘要扫描器、验证器循环、共识解码。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

目前暴露了九个工具：

生成工具上的 use_brain 标志会自动将当前工作目录中的 .brain/context.md 预置到系统提示词中，因此项目特定的上下文会随每次调用传递，无需 Claude 手动传递。

要求

• Python 3.11+

• Ollama — 下载适用于你操作系统的版本。已在 Windows 原生环境测试，通过 localhost:1434 通信。

• 本地拉取的编码模型：

  ollama pull qwen2.5-coder:14b

  约 9 GB 下载。在 12 GB 显存下可运行 Q5 版本。其他模型也适用（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

将 CodeBrain 添加到你的 Claude Code MCP 配置中。在 Windows 上，通常是 ~/.claude.json（请根据你克隆代码的路径调整）：

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

重启任何 Claude Code 会话——五个 codebrain_* 工具现在应该出现在可用工具列表中。

自动保持大脑文件同步

一旦你在仓库中运行了 codebrain_init 并使用 codebrain_scan_repo 进行了扫描，你可能希望在 Claude 编辑源码时自动刷新大脑文件。通过以下两部分实现：

1. 项目 CLAUDE.md 片段 — 告诉 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 钩子 — 在每次编辑/写入后重新生成大脑文件。

添加到仓库根目录的 .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] 三个核心工具：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 阶段 — 大脑系统 ✓

逐文件的 <source>.brain 摘要位于每个源文件旁边。Claude 先读取大脑，仅在信息不足时才打开源码。

• [x] codebrain_scan_file(path, force) — 生成或刷新一个大脑文件

• [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 仅写入五个部分

• [x] 深度防御验证：栅栏剥离、跳过空源（<10 字符）、部分存在/顺序检查、无效时重试

• [x] CLAUDE.md 约定 + 本 README 中的 PostToolUse 钩子片段

第 3 阶段 — 验证器循环 ✓

狗粮测试显示本地模型在文本转换上会产生偏差。验证器在结果到达 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 （已推迟 — 非瓶颈）

大脑文件已经充当了索引；只有在未来的使用确实表明索引是瓶颈时，跨文件 RAG 才有意义。目前没有相关信号，因此未构建。

许可证

MIT — 见 LICENSE。