ccrag
A RAG pipeline for Claude Code. Indexes your codebase locally and exposes it as an MCP server so Claude Code can semantically search your code during sessions.
How it works
ccrag index . → AST-chunks your code + embeds with sentence-transformers
stores vectors in .ccrag/ (LanceDB, stays in your repo)
ccrag serve . → MCP server (stdio) that Claude Code connects to
exposes search_codebase("how does auth work?") as a tool
Claude Code → automatically calls search_codebase when it needs context
gets back file paths, line ranges, and code snippets
Install
pip install ccrag
Usage
1. Index your codebase
cd /your/project
ccrag index .
2. Get the MCP config snippet
ccrag mcp-config .
This prints a JSON block to paste into .claude/settings.json:
{
"mcpServers": {
"ccrag": {
"command": "/path/to/ccrag",
"args": ["serve", "/your/project"]
}
}
}
3. Start a Claude Code session
Claude Code will now automatically call search_codebase whenever it needs to understand the codebase. No changes to your prompts needed.
Commands
| Command | Description |
|---|---|
ccrag index [PATH] |
Index or re-index the codebase |
ccrag index --force [PATH] |
Drop and rebuild the index |
ccrag serve [PATH] |
Start the MCP server (used by Claude Code) |
ccrag watch [PATH] |
Watch for file changes and re-index incrementally |
ccrag status [PATH] |
Show index stats (files, chunks) |
ccrag mcp-config [PATH] |
Print the settings.json snippet |
How the index works
- Chunking: Uses tree-sitter to split code at function/class/method boundaries — not arbitrary line windows. Falls back to line-window chunking for unsupported languages.
- Embeddings:
mixedbread-ai/mxbai-embed-large-v1viasentence-transformers— 1024-dim, top-tier MTEB retrieval, runs entirely locally with no API keys and no remote code. Override with--model <name>(e.g. a lighter model likeBAAI/bge-base-en-v1.5, or a code-specialized one likejinaai/jina-embeddings-v2-base-code, which needstrust_remote_code=Trueand a compatibletransformers). - Model cache: weights are cached in
.ccrag/models/on first run and reused offline afterward — downloaded once, never again. - Storage: LanceDB in
.ccrag/inside your project. Add.ccrag/to.gitignore. - Search: Cosine similarity over dense embeddings. Returns top-K chunks with file path, line range, language, and source.
Supported languages
Python, JavaScript, TypeScript, TSX, Go, Rust, Java, C, C++, Ruby, PHP, C#, Swift, Kotlin, Scala, Lua, Elixir, Haskell, OCaml, Bash, YAML, JSON, TOML, Markdown, and more.
MCP tools exposed
| Tool | Description |
|---|---|
search_codebase(query, n_results=8) |
Semantic search over indexed code |
codebase_stats() |
Number of indexed files and chunks |
Incremental updates
ccrag index . is incremental. It keeps a manifest of per-file content hashes in .ccrag/manifest.json and on each run:
- skips unchanged files entirely — no re-chunking, no re-embedding (the expensive step);
- re-embeds only changed/new files;
- prunes chunks for deleted files;
- rebuilds from scratch if you switch
--model(old vectors are incompatible).
So re-running it after editing a few files only touches those files:
$ ccrag index .
Found 20 files (1 new/changed, 19 unchanged, 0 removed)
Done. 3 chunks from 1 file(s) embedded, 0 file(s) removed.
For continuous updates, run the watcher, which re-indexes each file on save (and keeps the manifest in sync):
ccrag watch .
License
MIT
Metadata
Release files for ccrag 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ccrag-0.1.0.tar.gz | 18.0 kB | Without provenance | Details for ccrag-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ccrag-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for ccrag-0.1.0-py3-none-any.whl |
Total release size: 31.3 kB
Release files / ccrag-0.1.0.tar.gz
| Download URL | ccrag-0.1.0.tar.gz |
|---|---|
| Size | 18.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
74c6a321254d30233667e28a8285ea79df6b115b4ac7f0d7071225fe1b0cdeed
|
|
BLAKE2b-256 checksum How to use checksums |
bc6050777c600588d06c3c6a1f727add1dc688f2b6e07b0ebe7598b9962a2740
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / ccrag-0.1.0-py3-none-any.whl
| Download URL | ccrag-0.1.0-py3-none-any.whl |
|---|---|
| Size | 13.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
09f1ee27582ae8a59bdd28def52f6bd44d5ca7b612415f83030f04fc2b0c9229
|
|
BLAKE2b-256 checksum How to use checksums |
9c0ba11eb1c0982840ce4bb2b3536ecdbaa269f03d4e6f05c75d1241e44064d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for ccrag 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.