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

> Easily set up code-graph-rag for local development with our complete installation guide. Install dependencies, configure your environment, and launch the code analysis stack in minutes.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: getting-started
- Published: 2026-08-14

---

**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`](https://github.com/vitali87/code-graph-rag/blob/main/docs/getting-started/installation.md) in the repository.

## Clone and Install the Package

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

```bash

# 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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants/security.py).

```bash
cp .env.example .env

```

Edit `.env` with your LLM provider credentials:

```bash

# 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`](https://github.com/vitali87/code-graph-rag/blob/main/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:

```bash
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:

```bash

# 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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/services/graph_service.py).

**Subsequent sessions** skip re-parsing:

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

```

**Fresh start** (purge and re-index):

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

```

## Interact with the RAG CLI

Once indexed, the CLI provides an interactive multiline REPL:

```bash
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`](https://github.com/vitali87/code-graph-rag/blob/main/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:

```bash
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`](https://github.com/vitali87/code-graph-rag/blob/main/docs/guide/mcp-server.md) for protocol details.

## Verify Your Setup

Run diagnostics to confirm all components:

```bash
cgr doctor

```

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

## Complete Setup Example

```bash

# 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`:

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/pyproject.toml) specifies this minimum, and earlier versions lack required typing features used in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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.