CodeBrain

MCP-сервер, который позволяет Claude Code перекладывать объемную работу на локальную LLM, запущенную на вашем собственном оборудовании.

Что это (и чем не является)

Является: MCP-сервером (Model Context Protocol), который Claude Code регистрирует в качестве бэкенда для вспомогательного агента. Когда сессия включает задачи, с которыми хорошо справляется локальная модель кодинга на 14B параметров — создание 50 шаблонов событий, доработка 20 React-компонентов, написание шаблонного кода — Claude Code обращается к CodeBrain вместо того, чтобы тратить свои собственные выходные токены. Локальная модель делает черновой вариант, а 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 — скачать для вашей ОС. Протестировано с Ollama на Windows (нативная версия), взаимодействие через localhost:11434.

• Локально загруженная модель для кодинга:

  ollama pull qwen2.5-coder:14b

  ~9 ГБ загрузки. Помещается в 12 ГБ видеопамяти при 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 в конфигурацию MCP Claude Code. В Windows это обычно ~/.claude.json (отрегулируйте путь к месту, куда вы клонировали репозиторий):

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

Перезапустите любую сессию Claude Code — пять инструментов codebrain_* теперь должны появиться в списке доступных инструментов.

Автоматическая синхронизация brain-файлов

После того как вы запустили codebrain_init в репозитории и просканировали его с помощью codebrain_scan_repo, вы, вероятно, захотите, чтобы brain-файлы обновлялись автоматически всякий раз, когда Claude редактирует исходный код. Это настраивается двумя способами:

1. Фрагмент CLAUDE.md — скажите Claude читать brain-файлы перед открытием исходного кода:

## 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 после каждого Edit/Write.

Добавьте в .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] HTTP-клиент Ollama с обработкой ошибок

• [x] FastMCP-сервер с транспортом stdio

• [x] Три основных инструмента: generate, explain, status

• [x] Документированная настройка + конфигурация Claude Code

• [x] Проверено в реальной сессии Claude Code

Фаза 2 — пакетная обработка и контекст ✓

• [x] codebrain_batch_generate для массового контента с одним общим системным промптом, ошибки с сохранением индекса

• [x] codebrain_polish для целевых преобразований (сокращение / перефразирование / перевод) вместо перегенерации

• [x] Передача .brain/context.md — контекст проекта из cwd автоматически добавляется к каждому вызову генерации

• [x] Dogfooding: задачи по кодингу работают стабильно, задачи по преобразованию текста выявили реальные ограничения (информирует Фазу 3)

Фаза 2.5 — система brain ✓

Сводки <source>.brain для каждого файла располагаются рядом с исходным файлом. Claude сначала читает brain и открывает исходный код только тогда, когда информации в brain недостаточно.

• [x] codebrain_scan_file(path, force) — создание или обновление одного brain-файла

• [x] codebrain_scan_repo(root, force, extensions, exclude_dirs) — массовый обход + сканирование

• [x] codebrain_init(root, force) — инициализация .brain/context.md с определением стека

• [x] Перегенерация с хеш-защитой (SHA256) — идемпотентные повторные запуски

• [x] Программный frontmatter — детерминированные source, source_hash, model; Qwen записывает только пять разделов

• [x] Глубокая проверка: удаление ограждений, пропуск пустых исходников (<10 символов), наличие/порядок разделов, повтор при невалидности

• [x] Соглашение CLAUDE.md + фрагмент хука PostToolUse в этом README

Фаза 3 — цикл ВЕРИФИКАТОРА ✓

Dogfooding показал, что локальная модель «уплывает» при преобразовании текста. Верификатор детерминированно отлавливает отсутствие изменений, нарушения длины и несоответствия схеме до того, как они попадут к 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.