CodeRAG

Intelligent codebase context engine for AI coding agents.

CodeRAG creates a semantic vector database (RAG) from your source code, documentation, and project backlog, then exposes it as MCP tools that give AI agents deep understanding of your entire codebase.

Features

• AST-based code parsing -- Tree-sitter parses source code into semantically meaningful chunks (functions, classes, methods), not arbitrary line splits
• Natural language enrichment -- Each code chunk is summarized in plain English before embedding, improving search quality by up to 10x
• Hybrid search -- Combines vector similarity (semantic) with BM25 (keyword) using Reciprocal Rank Fusion
• Dependency graph expansion -- After finding relevant chunks, expands results using the code dependency graph (tests, interfaces, callers)
• Token budget optimization -- Assembles context within an agent's token budget, prioritized by relevance
• MCP server with 6 tools -- coderag_search, coderag_context, coderag_explain, coderag_status, coderag_docs, coderag_backlog
• Incremental indexing -- Only changed files are re-processed on subsequent runs
• Multi-repo support -- Index and search across multiple repositories seamlessly
• Backlog integration -- Azure DevOps, Jira, and ClickUp support
• Documentation indexing -- Markdown, Confluence, and SharePoint
• Multiple embedding providers -- Auto (default, manages Ollama lifecycle), Ollama, OpenAI-compatible, Voyage, OpenAI
• Multiple vector stores -- LanceDB (embedded, zero-infra), Qdrant
• Web viewer -- Dashboard, search playground, dependency graph, UMAP embedding explorer
• VS Code extension -- Search panel and auto-MCP configuration
• REST API server -- Team/cloud deployment with auth, RBAC, and audit logging
• Local-first, privacy-first -- Everything works offline; code never leaves your machine without explicit opt-in

Architecture

flowchart LR
    subgraph Sources
        S1[Git Repos]
        S2[Backlog\nADO / Jira / ClickUp]
        S3[Docs\nConfluence / SharePoint / MD]
    end

    subgraph Ingestion["Ingestion Pipeline"]
        P[Tree-sitter\nAST Parser]
        C[AST Chunker]
        E[NL Enrichment\nOllama]
    end

    subgraph Storage["Storage Layer"]
        V[LanceDB / Qdrant\nVector Store]
        B[MiniSearch\nBM25 Index]
        G[Dependency\nGraph]
    end

    subgraph Retrieval["Retrieval Engine"]
        H[Hybrid Search\n+ RRF]
        X[Graph Expansion\n+ Re-ranking]
        T[Token Budget\nOptimizer]
    end

    subgraph Interface["Agent Interface"]
        M[MCP Server\n6 Tools]
        R[REST API]
        VS[VS Code\nExtension]
        VW[Web Viewer]
    end

    S1 & S2 & S3 --> P --> C --> E --> V & B & G
    V & B & G --> H --> X --> T
    T --> M & R & VS & VW

Quick Start

Prerequisites: Node.js >= 20, Ollama running with nomic-embed-text and qwen2.5-coder:7b models pulled.

# 1. Install
npm install -g @code-rag/cli

# 2. Initialize in your project directory
coderag init

# 3. Index your codebase
coderag index

# 4. Search
coderag search "how does authentication work"

That is it. CodeRAG will parse your code into AST chunks, enrich them with natural language summaries, create embeddings, and build a hybrid search index. Subsequent coderag index runs are incremental -- only changed files are re-processed.

Start the MCP server for AI agents

# stdio transport (default, for direct agent integration)
coderag serve

# SSE transport (for network access)
coderag serve --port 3000

Connect to Claude Desktop

Add to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "coderag": {
      "command": "npx",
      "args": ["coderag", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

Packages

CLI Commands

Web Viewer

CodeRAG includes a built-in web viewer for visually exploring your indexed codebase.

coderag viewer

Opens http://localhost:3333 with five views:

See packages/viewer/ for details.

MCP Tools

Tech Stack

Benchmarks

Evaluated on 55 curated queries against the CodeRAG codebase itself (easy/medium/hard, function lookups to cross-file reasoning). Grep uses keyword extraction as a baseline.

Run pnpm benchmark to reproduce. See packages/benchmarks/ for the full dataset and methodology.

Documentation

See the docs/ directory for additional documentation.

Development

# Clone and install
git clone https://github.com/maciek-O-digiaidev/CodeRAG.git
cd CodeRAG
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run benchmarks
pnpm benchmark

License

MIT