CodeBrain

Claude Code가 자신의 하드웨어에서 실행되는 로컬 LLM으로 대량의 작업을 오프로드할 수 있게 해주는 MCP 서버입니다.

이것은 무엇인가 (그리고 무엇이 아닌가)

무엇인가: Claude Code가 서브 에이전트 백엔드로 등록하는 MCP(Model Context Protocol) 서버입니다. 세션에 14B 로컬 코더 모델이 잘 처리할 수 있는 작업(이벤트 템플릿 50개 생성, React 컴포넌트 20개 다듬기, 보일러플레이트 작성 등)이 포함될 때, Claude Code는 자신의 출력 토큰을 소모하는 대신 CodeBrain을 호출합니다. 로컬 모델이 초안을 작성하고, Claude는 이를 검토하고 적용합니다.

무엇이 아닌가: Claude 대체재가 아닙니다. 추론, 아키텍처 결정, 디버깅 및 "적당히 좋은" 것으로는 부족한 모든 작업은 Claude가 담당합니다. CodeBrain은 Claude 경쟁자가 아니라 Claude 오프로더입니다.

이유: 대량의 콘텐츠 및 다듬기 작업은 Claude의 컨텍스트와 속도 제한을 빠르게 소모합니다. 무제한으로 실행할 수 있는 로컬 모델은 호출당 추가 비용이 들지 않으며, 세션의 어려운 부분을 위해 고가치의 컨텍스트를 자유롭게 유지할 수 있게 해줍니다.

Related MCP server: ollama-mcp

상태

1~4단계 완료, 5단계 보류. 9개의 도구 노출, .brain/context.md 패스스루 라이브, 파일별 브레인 요약 스캐너, 검증 루프, 합의 디코딩이 구현되었습니다. 실제 Claude Code 세션에서 MCP 통합이 검증되었습니다. 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_* 도구가 사용 가능한 도구 목록에 나타납니다.

브레인 파일을 자동으로 동기화 유지

저장소에서 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] 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단계 — 브레인 시스템 ✓

파일별 <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은 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 추론 호출, 분산이 큰 작업의 품질 향상.

• 다중 패스 skeleton→logic→edges→polish: 보류 (측정된 가치가 낮음; 개별 도구로 이미 구성 가능).

5단계 — RAG (보류 — 병목 현상 아님)

브레인 파일이 이미 인덱스 역할을 합니다. 파일 간 RAG는 향후 인덱싱이 병목 현상임이 입증될 때만 의미가 있습니다. 현재는 그런 신호가 없어 구축하지 않았습니다.

라이선스

MIT — LICENSE 참조.