Skip to main content

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-v1 via sentence-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 like BAAI/bge-base-en-v1.5, or a code-specialized one like jinaai/jina-embeddings-v2-base-code, which needs trust_remote_code=True and a compatible transformers).
  • 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)

Source distribution for ccrag 0.1.0
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)

Table of built distributions (wheels) for ccrag 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page