CodeBrain

GitHub

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

CodeBrain

CodeBrain

Features

Quick Start

1. Install

2. Start Ollama and pull a code model

3. Index your codebase

4. Ask questions

5. Launch web UI

Configuration (`config.yaml`)

Key options

MCP Server Setup

Cursor

Claude Code

Cline

CLI Reference

Architecture

Notes

License

Latest Blog Posts

MCP directory API

CodeBrain

Features

Quick Start

1. Install

2. Start Ollama and pull a code model

3. Index your codebase

4. Ask questions

5. Launch web UI

Configuration (config.yaml)

Key options

MCP Server Setup

Cursor

Claude Code

Cline

CLI Reference

Architecture

Notes

License

Latest Blog Posts

MCP directory API

Configuration (`config.yaml`)