# CodeBrain

[![GitHub](https://img.shields.io/badge/GitHub-liuwanwan1%2FCodeBrain-blue?logo=github)](https://github.com/liuwanwan1/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

```bash
pip install -r requirements.txt
```

### 2. Start Ollama and pull a code model

```bash
ollama pull deepseek-coder:6.7b
ollama serve
```

You can change the model in `config.yaml`.

### 3. Index your codebase

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

Add `--watch` to monitor file changes:

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

### 4. Ask questions

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

### 5. Launch web UI

```bash
python -m codebrain web
```

Open `http://127.0.0.1:7860`.

## Configuration (`config.yaml`)

```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`:

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

### Claude Code

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

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

### Cline

Add to Cline MCP settings:

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

## CLI Reference

```bash
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