CodeBrain

CodeBrain（代码知识库大脑）is a local AI assistant that understands your codebase. It uses RAG (Retrieval-Augmented Generation) with a local embedding model and local LLM (Ollama/DeepSeek), exposes an MCP server for external AI tools, and provides a simple Gradio web UI.

Features

• Codebase indexing: auto-scan Python / Java / Go / JavaScript / TypeScript repositories
• Semantic search: vectorize code chunks (functions, classes, modules) with sentence-transformers
• Local vector DB: persist embeddings with ChromaDB
• Natural-language Q&A: retrieve relevant snippets and generate answers with line-number citations
• Incremental updates: re-index only changed files; optional file-system watcher
• MCP server: expose codebrain_search and codebrain_status tools to Cursor / Claude Code / Cline
• Web UI: chat + index project + view status

Quick Start

1. Install

pip install -r requirements.txt

2. Start Ollama and pull a code model

ollama pull deepseek-coder:6.7b
ollama serve

You can change the model in config.yaml.

3. Index your codebase

python -m codebrain index /path/to/your/codebase

Add --watch to monitor file changes:

python -m codebrain index /path/to/your/codebase --watch

4. Ask questions

python -m codebrain ask "用户登录功能在哪个文件里实现的？"

5. Launch web UI

python -m codebrain web

Open http://127.0.0.1:7860.

Configuration (config.yaml)

project:
  supported_languages:
    - python
    - java
    - go
    - javascript
    - typescript
  ignore_patterns:
    - node_modules
    - .git
    - __pycache__
    - .venv
    - venv
    - dist
    - build
    - target
    - .idea
    - .vscode
    - .codebrain
    - ".mypy_cache"
    - ".pytest_cache"

indexer:
  embedding_model: all-MiniLM-L6-v2   # sentence-transformers model
  chunk_size: 512
  chunk_overlap: 50

vector_store:
  provider: chromadb
  persist_directory: .codebrain/chroma_db
  collection_name: codebrain

llm:
  provider: ollama
  model: deepseek-coder:6.7b
  base_url: http://localhost:11434
  temperature: 0.1
  max_tokens: 2048

web:
  host: 127.0.0.1
  port: 7860

mcp:
  transport: stdio

Key options

Section	Option	Description
project	supported_languages	Languages to index
project	ignore_patterns	Glob patterns for directories/files to skip
indexer	embedding_model	HuggingFace sentence-transformers model name
vector_store	persist_directory	Where ChromaDB stores vectors
llm	model	Ollama model tag
llm	base_url	Ollama server URL
web	host / port	Gradio server bind address

MCP Server Setup

CodeBrain implements an MCP server over stdio. Tools exposed:

• codebrain_search(query, top_k=5, language="") — search the knowledge base
• codebrain_status() — show index statistics

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "codebrain": {
      "command": "python",
      "args": ["-m", "codebrain", "mcp"],
      "cwd": "/absolute/path/to/codebrain"
    }
  }
}

Claude Code

Add to ~/.claude-code/settings.json:

{
  "mcpServers": {
    "codebrain": {
      "command": "python",
      "args": ["-m", "codebrain", "mcp"]
    }
  }
}

Cline

Add to Cline MCP settings:

{
  "mcpServers": {
    "codebrain": {
      "command": "python",
      "args": ["-m", "codebrain", "mcp"],
      "env": {},
      "disabled": false,
      "autoApprove": ["codebrain_search", "codebrain_status"]
    }
  }
}

CLI Reference

python -m codebrain --help
python -m codebrain index <path> [--watch]
python -m codebrain status
python -m codebrain ask "question" [--language python]
python -m codebrain web
python -m codebrain mcp

Architecture

codebrain/
├── config.py          # Configuration loading
├── models.py          # CodeChunk / RetrievalResult dataclasses
├── indexer/
│   ├── parser.py      # Python AST + regex-based parser for Java/Go/JS/TS
│   ├── embedder.py    # sentence-transformers wrapper
│   ├── store.py       # ChromaDB wrapper
│   ├── indexer.py     # Scan / embed / upsert orchestration
│   └── watcher.py     # File-system watcher for incremental updates
├── rag/
│   ├── llm.py         # Ollama client
│   └── engine.py      # RAG retrieval + generation
├── mcp_server/
│   └── server.py      # MCP server implementation
├── web/
│   └── app.py         # Gradio chat UI
└── main.py            # CLI entry point

Notes

• First indexing downloads the embedding model and may take a few minutes.
• Make sure Ollama is running before using ask / web / MCP tools.
• The vector store is stored locally in .codebrain/chroma_db by default.

License

MIT