• 🌳 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