Code-Graph-RAG: A Graph-Based RAG System for Any Codebases

An accurate Retrieval-Augmented Generation (RAG) system that analyzes multi-language codebases using Tree-sitter, builds comprehensive knowledge graphs, and enables natural language querying of codebase structure and relationships as well as editing capabilities.

Latest News 🔥

• PHP Language Support: Full PHP language support added — classes, interfaces, traits, enums, namespaces, PHP 8 attributes, and call graph analysis. Contributed by @rs-ipps.
• C Language Support: Full C language support added — functions, structs, unions, enums, preprocessor includes, and call graph analysis. Contributed by @dj0nes.
• Visualise any GitHub repo instantly! Just change github.com to gitcgr.com in any repo URL — that's it, only 3 letters! Get an interactive graph of the entire codebase structure. Try it now: gitcgr.com

🚀 Features

• Multi-Language Support:

| Language | Status | Extensions | Functions | Classes/Structs | Modules | Package Detection | Additional Features | |--------|------|----------|---------|---------------|-------|-----------------|-------------------| | C | Fully Supported | .c | ✓ | ✓ | ✓ | ✓ | Functions, structs, unions, enums, preprocessor includes | | C++ | Fully Supported | .cpp, .h, .hpp, .cc, .cxx, .hxx, .hh, .ixx, .cppm, .ccm | ✓ | ✓ | ✓ | ✓ | Constructors, destructors, operator overloading, templates, lambdas, C++20 modules, namespaces | | Java | Fully Supported | .java | ✓ | ✓ | ✓ | - | Generics, annotations, modern features (records/sealed classes), concurrency, reflection | | JavaScript | Fully Supported | .js, .jsx | ✓ | ✓ | ✓ | - | ES6 modules, CommonJS, prototype methods, object methods, arrow functions | | Lua | Fully Supported | .lua | ✓ | - | ✓ | - | Local/global functions, metatables, closures, coroutines | | PHP | Fully Supported | .php | ✓ | ✓ | ✓ | - | Classes, interfaces, traits, enums, namespaces, PHP 8 attributes | | Python | Fully Supported | .py | ✓ | ✓ | ✓ | ✓ | Type inference, decorators, nested functions | | Rust | Fully Supported | .rs | ✓ | ✓ | ✓ | ✓ | impl blocks, associated functions | | TypeScript | Fully Supported | .ts, .tsx | ✓ | ✓ | ✓ | - | Interfaces, type aliases, enums, namespaces, ES6/CommonJS modules | | C# | In Development | .cs | ✓ | ✓ | ✓ | - | Classes, interfaces, generics (planned) | | Go | In Development | .go | ✓ | ✓ | ✓ | - | Methods, type declarations | | Scala | In Development | .scala, .sc | ✓ | ✓ | ✓ | - | Case classes, objects |

• 🌳 Tree-sitter Parsing: Uses Tree-sitter for robust, language-agnostic AST parsing
• 📊 Knowledge Graph Storage: Uses Memgraph to store codebase structure as an interconnected graph
• 🗣️ Natural Language Querying: Ask questions about your codebase in plain English
• 🤖 AI-Powered Cypher Generation: Supports both cloud models (Google Gemini), local models (Ollama), and OpenAI models for natural language to Cypher translation
• 🤖 OpenAI Integration: Leverage OpenAI models to enhance AI functionalities.
• 📝 Code Snippet Retrieval: Retrieves actual source code snippets for found functions/methods
• ✍️ Advanced File Editing: Surgical code replacement with AST-based function targeting, visual diff previews, and exact code block modifications
• ⚡️ Shell Command Execution: Can execute terminal commands for tasks like running tests or using CLI tools.
• 🚀 Interactive Code Optimization: AI-powered codebase optimization with language-specific best practices and interactive approval workflow
• 📚 Reference-Guided Optimization: Use your own coding standards and architectural documents to guide optimization suggestions
• 🔗 Dependency Analysis: Parses pyproject.toml to understand external dependencies
• 🎯 Nested Function Support: Handles complex nested functions and class hierarchies
• 🔄 Language-Agnostic Design: Unified graph schema across all supported languages

🏗️ Architecture

The system consists of two main components:

1. Multi-language Parser: Tree-sitter based parsing system that analyzes codebases and ingests data into Memgraph
2. RAG System (codebase_rag/): Interactive CLI for querying the stored knowledge graph

📋 Prerequisites

• Python 3.12+
• Docker & Docker Compose (for Memgraph)
• cmake (required for building pymgclient dependency)
• ripgrep (rg) (required for shell command text searching)
• For cloud models: Google Gemini API key
• For local models: Ollama installed and running
• uv package manager

Installing cmake and ripgrep

On macOS:

brew install cmake ripgrep

On Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install cmake ripgrep

On Linux (CentOS/RHEL):

sudo yum install cmake
sudo dnf install ripgrep
# Note: ripgrep may need to be installed from EPEL or via cargo

🛠️ Installation

git clone https://github.com/vitali87/code-graph-rag.git

cd code-graph-rag

2. Install dependencies:

For basic Python support:

uv sync

For full multi-language support:

uv sync --extra treesitter-full

For development (including tests and pre-commit hooks):

make dev

This installs all dependencies and sets up pre-commit hooks automatically.

This installs Tree-sitter grammars for all supported languages (see Multi-Language Support section).

3. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration (see options below)

Configuration Options

The new provider-explicit configuration supports mixing different providers for orchestrator and cypher models.

Option 1: All Ollama (Local Models)

# .env file
ORCHESTRATOR_PROVIDER=ollama
ORCHESTRATOR_MODEL=llama3.2
ORCHESTRATOR_ENDPOINT=http://localhost:11434/v1

CYPHER_PROVIDER=ollama
CYPHER_MODEL=codellama
CYPHER_ENDPOINT=http://localhost:11434/v1

Option 2: All OpenAI Models

# .env file
ORCHESTRATOR_PROVIDER=openai
ORCHESTRATOR_MODEL=gpt-4o
ORCHESTRATOR_API_KEY=sk-your-openai-key

CYPHER_PROVIDER=openai
CYPHER_MODEL=gpt-4o-mini
CYPHER_API_KEY=sk-your-openai-key

Option 3: All Google Models

# .env file
ORCHESTRATOR_PROVIDER=google
ORCHESTRATOR_MODEL=gemini-2.5-pro
ORCHESTRATOR_API_KEY=your-google-api-key

CYPHER_PROVIDER=google
CYPHER_MODEL=gemini-2.5-flash
CYPHER_API_KEY=your-google-api-key

Option 4: Mixed Providers

# .env file - Google orchestrator + Ollama cypher
ORCHESTRATOR_PROVIDER=google
ORCHESTRATOR_MODEL=gemini-2.5-pro
ORCHESTRATOR_API_KEY=your-google-api-key

CYPHER_PROVIDER=ollama
CYPHER_MODEL=codellama
CYPHER_ENDPOINT=http://localhost:11434/v1

Get your Google API key from Google AI Studio.

Install and run Ollama:

# Install Ollama (macOS/Linux)
curl -fsSL https://ollama.ai/install.sh | sh

# Pull required models
ollama pull llama3.2
# Or try other models like:
# ollama pull llama3
# ollama pull mistral
# ollama pull codellama

# Ollama will automatically start serving on localhost:11434

Note: Local models provide privacy and no API costs, but may have lower accuracy compared to cloud models like Gemini.

4. Start Memgraph database:

docker compose up -d

5. Verify installation:

# If installed from PyPI:
cgr --help

# If running from source:
uv run cgr --help

Note: When running from source (cloned repo), prefix all cgr commands below with uv run, e.g., uv run cgr start ...

🛠️ Makefile Commands

Use the Makefile for common development tasks:

| Command | Description | |-------|-----------| | make help | S