How to Set Up code-graph-rag for Local Development: Complete Installation Guide

Install Python 3.12+, Docker, and cmake, then run uv tool install "code-graph-rag[treesitter-full,semantic]", configure your .env file, and launch the stack with cgr daemon up and cgr start --repo-path /your/code --update-graph.

code-graph-rag is an open-source Retrieval-Augmented Generation (RAG) system that transforms codebases into queryable knowledge graphs. Built on Tree-sitter parsing and Memgraph storage, it enables natural language exploration of source code. This guide walks through the complete code-graph-rag local development setup using the official repository at vitali87/code-graph-rag.

Prerequisites for code-graph-rag Development

Before cloning the repository, ensure your system meets these requirements. The tool relies on external services for graph storage and optional vector search.

Required Dependencies

Component	Purpose	Installation
Python 3.12+	Core runtime	uv tool install python or system package manager
Docker & Docker Compose	Memgraph and Qdrant containers	https://docs.docker.com/get-docker/
cmake	Native pymgclient build	macOS: brew install cmake; Ubuntu: sudo apt-get install cmake
ripgrep (rg)	Fast file search internal utilities	macOS: brew install ripgrep; Ubuntu: sudo apt-get install ripgrep
uv (recommended) or pipx	Isolated Python package management	pip install uv
LLM client	Natural language to Cypher generation	Ollama, OpenAI, or Google Gemini

For Ollama specifically: curl -LO https://ollama.com/install.sh && sh install.sh

The full prerequisite documentation lives at docs/getting-started/installation.md in the repository.

Clone and Install the Package

The recommended installation path uses uv for fast, isolated dependency resolution.

# Clone the repository

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

# Install with full language support and semantic search

uv tool install "code-graph-rag[treesitter-full,semantic]"

# Alternative with pipx

# pipx install "code-graph-rag[treesitter-full,semantic]"

Installation options explained:

• treesitter-full — Installs all Tree-sitter grammars: Python, TypeScript, Rust, Go, Java, C, C++, C#, PHP, Lua, Dart, and others. See codebase_rag/constants/languages.py for the complete supported language list.
• semantic — Adds UniXcoder-based embeddings for semantic code search via Qdrant.

Configure Environment Variables

code-graph-rag reads configuration from a .env file via python-dotenv, as implemented in codebase_rag/constants/security.py.

cp .env.example .env

Edit .env with your LLM provider credentials:

# For Ollama local inference

OLLAMA_ENDPOINT=http://localhost:11434

# Or for OpenAI

OPENAI_API_KEY=sk-your-key-here

# Or for Google Gemini

GEMINI_API_KEY=your-gemini-key

No secrets are committed to the repository. The codebase_rag/config.py module validates these settings at runtime using Pydantic.

Launch the Memgraph Daemon

The bundled Docker Compose stack provides the graph database and optional vector store:

cgr daemon up

This command starts:

• Memgraph on port 7687 (Bolt protocol) with Memgraph Lab UI on port 3000
• Qdrant vector store for semantic search

The CLI blocks until health checks pass for both services.

Index a Codebase for Querying

To parse source files and populate the knowledge graph:

# First-time indexing with AST extraction and graph loading

cgr start --repo-path /path/to/your/repo --update-graph

The --update-graph flag triggers the full pipeline: Tree-sitter parsing of all supported files, entity extraction (functions, classes, modules, relationships), and batch insertion via MemgraphIngestor in codebase_rag/services/graph_service.py.

Subsequent sessions skip re-parsing:

cgr start --repo-path /path/to/your/repo

Fresh start (purge and re-index):

cgr start --repo-path /path/to/your/repo --clean

Interact with the RAG CLI

Once indexed, the CLI provides an interactive multiline REPL:

cgr start --repo-path /path/to/your/repo

Example queries:

• Code retrieval: show me the implementation of utils.calculate_total
• Dependency analysis: Which modules import pandas?
• AI-assisted refactoring: refactor utils.calculate_total to use list comprehension

The codebase_rag/main.py module orchestrates natural language-to-Cypher translation, graph execution, and tool-driven editing. Edits produce diff previews with confirmation prompts (bypass with --yolo or configure via confirm_edits).

Optional: Run the MCP Server

For external agent integration (e.g., Claude Code), start the Model Context Protocol server:

cgr server --repo-path /path/to/your/repo

Listens on port 8080 by default. Clients send natural language queries to GET /query and receive structured code graph responses. See docs/guide/mcp-server.md for protocol details.

Verify Your Setup

Run diagnostics to confirm all components:

cgr doctor

Checks: Docker daemon, Memgraph connectivity, Qdrant health, Python dependencies, and LLM credential validity.

Complete Setup Example

# 1. Clone and install

git clone https://github.com/vitali87/code-graph-rag.git
cd code-graph-rag
uv tool install "code-graph-rag[treesitter-full,semantic]"

# 2. Configure for Ollama

cp .env.example .env
sed -i 's|# OLLAMA_ENDPOINT=.*|OLLAMA_ENDPOINT=http://localhost:11434|' .env

# 3. Start infrastructure

cgr daemon up

# 4. Index target repository

cgr start --repo-path ~/projects/my-python-app --update-graph

# 5. Launch interactive session

cgr start --repo-path ~/projects/my-python-app

Programmatic API Usage

Embed code-graph-rag in Python scripts via GraphLoader:

from codebase_rag.sdk.graph_loader import GraphLoader

loader = GraphLoader(
    memgraph_host="localhost",
    memgraph_port=7687,
    batch_size=500,
)

loader.load_repo("/path/to/repo")

The load_repo() method wraps the same ingestion pipeline used by the CLI, as defined in codebase_rag/graph_loader.py.

Summary

• Install with uv tool install "code-graph-rag[treesitter-full,semantic]" for complete language support
• Configure LLM credentials in .env (Ollama, OpenAI, or Gemini)
• Launch infrastructure via cgr daemon up (Dockerized Memgraph + Qdrant)
• Index codebases with cgr start --repo-path /path --update-graph
• Query through natural language REPL or MCP server for agent integration
• Validate with cgr doctor before troubleshooting

Frequently Asked Questions

What Python version does code-graph-rag require?

Python 3.12 or higher. The pyproject.toml specifies this minimum, and earlier versions lack required typing features used in codebase_rag/config.py.

Can I use code-graph-rag without Docker?

No. Memgraph and Qdrant require containerized deployment for the cgr daemon up workflow. The pymgclient adapter also needs cmake to build native extensions. Docker provides the tested, supported path.

How do I add support for a new programming language?

Extend codebase_rag/constants/languages.py with the Tree-sitter grammar and AST node mappings. The treesitter-full extra includes pre-packaged grammars; custom languages need manual grammar installation.

Why is my indexing slow on large repositories?

Increase batch_size in GraphLoader or the CLI's --batch-size flag. The default batches 500 entities per transaction to MemgraphIngestor. For very large codebases, consider filtering with --include/--exclude patterns to parse only relevant subdirectories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}