CodeRAG - Verified Codebase Context Engine

CodeRAG is a verified codebase context engine for agents and developers. It indexes repositories, retrieves grounded code context, verifies citations against indexed snapshot evidence, and exposes the results through CLI, REST, MCP, and a local web UI. It is not an autonomous coding agent and does not edit repositories.

🚀 Quick Start

# Install
pip install code-rag-me

# Configure a cloud provider key, or skip generation with MODEL_PROFILE=retrieval-only
coderag setup

# Start web interface
coderag serve

Open http://localhost:8000 to use the web interface.

Minimal verified local flow

coderag index https://github.com/pallets/markupsafe
coderag repos --format json
coderag context-pack <repo-id-or-prefix> "escape function" --format json
coderag query <repo-id-or-prefix> "What does MarkupSafe's escape function do? Cite the relevant source lines." --format json

Expected completion signal: the query response has grounded: true, non-empty citations, non-empty citation_verifications, and evidence chunks. Use MODEL_PROFILE=retrieval-only for retrieval/context-pack workflows that must not require an LLM key.

Claude Desktop Integration (MCP)

# Auto-configure Claude Desktop
coderag mcp-install

# Restart Claude Desktop

After restart, Claude Desktop can use the local CodeRAG MCP tools configured by coderag mcp-install.

✨ Features

Verified citations: Answers include citations like [file:start-end], verify them against indexed file snapshots plus retrieved evidence, and fall back to deterministic evidence when a model omits or invents citations.
Hybrid retrieval and context packs: Combine semantic and lexical retrieval without requiring generation.
Code graph intelligence: Python and TypeScript/JavaScript symbols, references, and blast-radius evidence are indexed when supported.
Cloud or local LLM: Use Groq, OpenAI, Anthropic, OpenRouter, Together, or explicitly configured local models.
GitHub indexing: Index public GitHub repositories with durable SQLite registry/job state.
MCP support: Expose indexing, retrieval, context, and graph tools to MCP clients.
REST API and CLI: Programmatic and terminal access to the same core capabilities.
Local web interface: Gradio UI for local exploration.

📋 CLI Commands

coderag setup                         # Configure LLM provider and API key
coderag serve                         # Start local web/API/MCP server
coderag mcp-install                   # Configure Claude Desktop for MCP
coderag mcp-run                       # Run MCP server over stdio
coderag index <url>                   # Index a GitHub repository
coderag update <repo>                 # Incrementally update an indexed repository
coderag query <repo> "?"              # Ask a question with citations
coderag search-hybrid <repo> "query"  # Retrieve hybrid code context without generation
coderag context-pack <repo> "query"   # Build an agent-ready context pack
coderag find-symbol <repo> <symbol>   # Find indexed graph symbols
coderag find-references <repo> <sym>  # Find indexed symbol references
coderag blast-radius <repo> <symbol>  # Show graph-backed impacted files/tests
coderag repos                         # List indexed repositories
coderag doctor                        # Diagnose setup issues

🔧 Installation

Linux

Arch Linux / Manjaro

Arch Linux uses PEP 668 to protect system Python. Use one of these methods:

Option A: pipx (Recommended for CLI tools)

sudo pacman -S python-pipx
pipx install code-rag-me

Option B: Virtual environment

python -m venv ~/.local/share/coderag-venv
source ~/.local/share/coderag-venv/bin/activate
pip install code-rag-me

To always have coderag available, add to your ~/.bashrc or ~/.zshrc:

alias coderag="~/.local/share/coderag-venv/bin/coderag"

Debian / Ubuntu

# Install Python and pip
sudo apt update
sudo apt install python3 python3-pip python3-venv

# Option A: pipx (Recommended)
sudo apt install pipx
pipx install code-rag-me

# Option B: Virtual environment
python3 -m venv ~/.local/share/coderag-venv
source ~/.local/share/coderag-venv/bin/activate
pip install code-rag-me

Fedora / RHEL / CentOS

# Install Python and pip
sudo dnf install python3 python3-pip

# Option A: pipx (Recommended)
sudo dnf install pipx
pipx install code-rag-me

# Option B: Virtual environment
python3 -m venv ~/.local/share/coderag-venv
source ~/.local/share/coderag-venv/bin/activate
pip install code-rag-me

Other Linux Distributions

# Create virtual environment
python3 -m venv ~/.local/share/coderag-venv
source ~/.local/share/coderag-venv/bin/activate
pip install code-rag-me

macOS

Option A: pipx (Recommended)

# Install pipx via Homebrew
brew install pipx
pipx ensurepath
pipx install code-rag-me

Option B: Virtual environment

python3 -m venv ~/.local/share/coderag-venv
source ~/.local/share/coderag-venv/bin/activate
pip install code-rag-me

Option C: Homebrew Python

brew install python@3.11
pip3 install code-rag-me

Windows

Option A: pipx (Recommended)

# Install pipx
pip install pipx
pipx ensurepath

# Install CodeRAG
pipx install code-rag-me

Option B: Virtual environment

# Create virtual environment
python -m venv %USERPROFILE%\coderag-venv

# Activate (Command Prompt)
%USERPROFILE%\coderag-venv\Scripts\activate.bat

# Activate (PowerShell)
& $env:USERPROFILE\coderag-venv\Scripts\Activate.ps1

# Install
pip install code-rag-me

Option C: Direct install (not recommended)

pip install code-rag-me

Note: On Windows, you may need to run PowerShell as Administrator or enable script execution with Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

From Source

git clone https://github.com/Sebastiangmz/CodeRAG.git
cd CodeRAG
pip install -e .
coderag setup

Docker

git clone https://github.com/Sebastiangmz/CodeRAG.git
cd CodeRAG
docker compose up

Post-Installation

After installing, configure your LLM provider:

coderag setup

This will prompt you to:

Choose an LLM provider (Groq recommended - free tier available)
Enter your API key (get one at https://console.groq.com/keys)
Configure optional settings

📖 Usage Examples

Web Interface

Run coderag serve
Open http://localhost:8000
Go to "Index Repository" → Enter GitHub URL → Click "Index"
Go to "Ask Questions" → Select repo → Ask questions

Command Line

# Index a repository
coderag index https://github.com/owner/repo

# Ask questions with citation verification metadata
coderag query abc12345 "How does authentication work?" --format json

# Retrieve context without calling an LLM
coderag search-hybrid abc12345 "authentication flow" --format json
coderag context-pack abc12345 "authentication flow"

# Inspect graph evidence
coderag find-symbol abc12345 AuthService --format json
coderag find-references abc12345 validate_token --format json
coderag blast-radius abc12345 validate_token --format json

# List repositories
coderag repos

REST API

# Index repository
curl -X POST http://localhost:8000/api/v1/repos/index \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/owner/repo"}'

# Query with citation verification
curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"question": "How does X work?", "repo_id": "abc12345"}'

# Hybrid retrieval without generation
curl -X POST http://localhost:8000/api/v1/search-hybrid \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication flow", "repo_id": "abc12345", "top_k": 5}'

# Graph-backed blast radius
curl -X POST http://localhost:8000/api/v1/graph/blast-radius \
  -H "Content-Type: application/json" \
  -d '{"symbol": "validate_token", "repo_id": "abc12345"}'

Claude Desktop (MCP)

After running coderag mcp-install and restarting Claude Desktop:

You: Use coderag to index https://github.com/owner/repo

Claude: I'll index that repository for you...
        ✅ Indexed! 150 files, 1,234 chunks.

You: How does the authentication system work?

Claude: Based on the code, authentication is handled in...
        [src/auth/handler.py:45-78]

⚙️ Configuration

Environment Variables

# LLM Provider (groq, openai, anthropic, openrouter, together, local)
MODEL_LLM_PROVIDER=groq
MODEL_LLM_API_KEY=your-api-key

# Embeddings (runs locally on CPU by default)
MODEL_EMBEDDING_DEVICE=auto  # auto, cuda, or cpu

# Server defaults to loopback for local safety.
SERVER_HOST=127.0.0.1
SERVER_PORT=8000

# Bind to 0.0.0.0 only as an explicit deployment override
# after configuring trusted CORS origins and network access controls.

Config File

Configuration is stored in ~/.config/coderag/config.json after running coderag setup.

Production readiness and evidence

CodeRAG is complete for the portfolio/local-product scope: a verified codebase context engine with CLI, REST, MCP, and local web UI surfaces. Current evidence covers a real local MarkupSafe indexing/query flow with generated answers, grounded citations, context packs, API, MCP, CLI, UI screenshots, and negative cases.

What is claimed:

Local loopback operation (127.0.0.1) with user-configured model credentials.
Durable SQLite repository/job state, hybrid retrieval, graph-backed code intelligence where supported, and deterministic citation verification against indexed snapshots.
Safe default posture: trusted CORS is required for non-local browser origins, remote model code is disabled unless explicitly configured, and retrieval-only workflows can run without an LLM key.
Unsupported graph languages degrade explicitly to text/chunk retrieval; they do not report fake graph confidence.

What is not claimed:

Hosted SaaS or multi-user production deployment readiness.
That CodeRAG proves repository correctness, executes arbitrary project tests, or makes autonomous code changes.
Physical headed-browser proof in every harness. The latest local UI E2E captured DOM/screenshot evidence; if a visible browser is required, run the same frozen plan with a headed Playwright-capable driver.

Evidence:

Portfolio completion plan: docs/superpowers/plans/2026-07-02-coderag-portfolio-complete.md
Real local E2E plan and run record: docs/superpowers/plans/2026-07-02-coderag-portfolio-e2e-plan.md, docs/superpowers/plans/2026-07-02-coderag-portfolio-e2e-run-record.md
Portfolio readiness review: docs/superpowers/plans/2026-07-02-coderag-portfolio-readiness-review.md
M7 release-candidate evidence: docs/superpowers/plans/2026-06-30-m7-release-run-record.md, evals/runs/20260630-m7-production-rc.json, evals/reports/20260630-m7-production-rc.md

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                         User Interface                       │
│              (Gradio UI / REST API / MCP / CLI)             │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────────────┐
│                     Ingestion Pipeline                        │
│  GitHub Clone → File Filter → Chunker (Tree-sitter/Text)    │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────────────┐
│                   Indexing & Storage                          │
│      Embeddings (nomic-embed) → ChromaDB (Cosine)           │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────────────┐
│                    Retrieval & Generation                     │
│   Query → Top-K Search → LLM (Cloud/Local) → Response       │
└──────────────────────────────────────────────────────────────┘

📁 Project Structure

src/coderag/
├── cli.py          # Unified CLI
├── ingestion/      # Repository loading and chunking
├── indexing/       # Embeddings and vector storage
├── retrieval/      # Semantic search
├── generation/     # LLM inference and citations
├── mcp/            # Model Context Protocol server
├── ui/             # Gradio web interface
├── api/            # REST API endpoints
└── models/         # Data models

🧪 Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

📊 Performance

Indexing: ~1000 files in < 5 minutes
Query: Response in < 10 seconds
Embeddings: Runs on CPU (~275MB model)
LLM: Cloud (instant) or Local (requires 8GB+ VRAM)

📝 Citation Format

All responses include citations:

[file_path:start_line-end_line]

Example:

The authentication logic is in the login() function [src/auth.py:45-78].

🐛 Troubleshooting

Run diagnostics:

coderag doctor

Common Issues

`externally-managed-environment` error (Linux)

error: externally-managed-environment
× This environment is externally managed

This happens on modern Linux distributions (Arch, Fedora 38+, Ubuntu 23.04+) that implement PEP 668. Solution: use pipx or a virtual environment. See the Installation section for your distribution.

No API key configured

coderag setup  # Run interactive setup

CUDA / GPU errors

If you don't have a GPU or encounter CUDA errors:

export MODEL_EMBEDDING_DEVICE=cpu
coderag serve

Or add to your .env file:

MODEL_EMBEDDING_DEVICE=cpu

Claude Desktop not detecting MCP

Run coderag mcp-install
Completely quit Claude Desktop (not just close the window)
Restart Claude Desktop
Check the MCP icon in Claude Desktop settings

Permission denied on Linux/macOS

# If using pipx
pipx ensurepath
source ~/.bashrc  # or ~/.zshrc

# If using venv, make sure it's activated
source ~/.local/share/coderag-venv/bin/activate

PowerShell execution policy (Windows)

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

📄 License

MIT License - see LICENSE file

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

🙏 Acknowledgments

Groq for fast, free LLM inference
nomic-embed-text by Nomic AI
ChromaDB for vector storage
Tree-sitter for code parsing
MCP by Anthropic

Name		Name	Last commit message	Last commit date
.github		.github
.pi		.pi
configs		configs
docs/superpowers/plans		docs/superpowers/plans
eval_datasets		eval_datasets
evals		evals
scripts		scripts
src/coderag		src/coderag
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
app.py		app.py
docker-compose.yaml		docker-compose.yaml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation