How to Configure code-graph-rag: Environment Variables, CLI Flags, and Code Examples

Configure code-graph-rag by setting required environment variables like OPENAI_API_KEY, using CLI flags such as --repo and --vector-store, or instantiating the CGRConfig dataclass programmatically to control the graph-building and RAG pipeline.

code-graph-rag is a Python framework that constructs a graph representation of any codebase and enables semantic search via Retrieval-Augmented Generation (RAG). According to the vitali87/code-graph-rag source code, the system aggregates settings through three primary mechanisms: environment variables, command-line interface (CLI) arguments, and configuration objects defined in codebase_rag/workspaces/models.py.

Configuration Mechanisms

Environment Variables

The framework reads critical secrets and endpoint URLs from the environment before invoking external APIs. In codebase_rag/workspaces/constants.py, the following variables are declared as required or optional defaults:

• OPENAI_API_KEY – Your OpenAI API token for generating embeddings and completions.
• VECTOR_STORE_URL – Endpoint URL for the vector store backend (e.g., Pinecone, Weaviate, or local Qdrant).
• VECTOR_STORE_API_KEY – Authentication token for the vector store provider, if applicable.

Set these in your shell or .env file before running the pipeline.

CLI Flags

The cgr command-line interface, implemented in codebase_rag/workspaces/cli.py, exposes parameters that override environment defaults. Key flags include:

• --repo – URL or local path to the target Git repository.
• --embedder – Embedding provider selection (e.g., openai, huggingface).
• --vector-store – Backend for vector storage (e.g., qdrant, pinecone).
• --output-dir – Workspace directory for generated graphs and logs (default: ./cgr_workspace).
• --embedder-model – Specific model name, such as text-embedding-ada-002.
• --chunk-size – Number of lines per code chunk to embed.
• --prune-threshold – Similarity threshold below which graph edges are removed to reduce noise.

Programmatic Configuration

For custom applications, instantiate the CGRConfig dataclass directly and pass it to the RAGEngine class defined in codebase_rag/rag_engine.py. This approach bypasses CLI parsing and environment variable scanning, allowing dynamic configuration at runtime.

Step-by-Step Setup Guide

Follow these steps to configure and run the pipeline:

1. Install dependencies
   Run pip install -r requirements.txt to install the required packages listed in the repository root.

2. Export environment variables

   export OPENAI_API_KEY="sk-..."
   export VECTOR_STORE_URL="http://localhost:6333"
   export VECTOR_STORE_API_KEY="optional-key"

3. Create a workspace directory
   Choose a folder to hold the generated graph, embeddings, and logs:

   mkdir -p ./cgr_workspace

4. Execute the CLI

   cgr \
     --repo https://github.com/your/project.git \
     --embedder openai \
     --vector-store qdrant \
     --output-dir ./cgr_workspace \
     --chunk-size 200

   This command clones the repository, parses the AST into a Neo4j-compatible graph, generates embeddings, and stores vectors in the configured backend.

5. Adjust advanced settings
   Modify --embedder-model to switch between OpenAI models, tune --chunk-size for optimal retrieval granularity, or set --prune-threshold 0.05 to filter low-relevance graph edges.

6. Query the resulting graph
   Use the REPL mode or import the engine directly:

   python -m codebase_rag.main --query "How does the authentication flow work?"

Key Configuration Files

Reference these source files when customizing behavior:

• codebase_rag/workspaces/constants.py – Declares environment variable keys and default constant values.
• codebase_rag/workspaces/models.py – Defines the CGRConfig Pydantic model that validates configuration schemas.
• codebase_rag/workspaces/cli.py – Implements the argparse logic that maps CLI flags to the config model.
• codebase_rag/main.py – Entry point that loads the config, initializes the graph builder, embedder, and vector store, then executes the pipeline.
• codebase_rag/embedder.py – Wrapper abstraction for embedding providers (OpenAI, HuggingFace).
• codebase_rag/vector_store.py – Interface for vector-store backends.

Configuration Code Examples

Programmatic Setup

from codebase_rag.rag_engine import RAGEngine
from codebase_rag.workspaces.models import CGRConfig

cfg = CGRConfig(
    repo_url="https://github.com/your/project.git",
    embedder="openai",
    embedder_model="text-embedding-ada-002",
    vector_store="qdrant",
    output_dir="./cgr_workspace",
    chunk_size=200,
)

engine = RAGEngine(cfg)
answer = engine.query("Explain the caching strategy used in the project.")
print(answer)

CLI Usage

cgr \
  --repo https://github.com/your/project.git \
  --embedder openai \
  --vector-store qdrant \
  --output-dir ./cgr_workspace \
  --chunk-size 300 \
  --prune-threshold 0.05

Summary

• Environment variables in codebase_rag/workspaces/constants.py handle secrets and endpoint URLs like OPENAI_API_KEY and VECTOR_STORE_URL.
• CLI flags parsed in codebase_rag/workspaces/cli.py allow runtime overrides for repository sources, embedding models, and output directories.
• The CGRConfig dataclass in codebase_rag/workspaces/models.py serves as the single source of truth, consumed by RAGEngine in codebase_rag/rag_engine.py.
• The entry point in codebase_rag/main.py orchestrates the pipeline: graph construction, embedding generation, and vector storage.

Frequently Asked Questions

What environment variables are required to run code-graph-rag?

You must set OPENAI_API_KEY for embedding generation and optional completions, plus VECTOR_STORE_URL to point to your vector database backend. If your vector store requires authentication, also set VECTOR_STORE_API_KEY. These names are defined in codebase_rag/workspaces/constants.py.

Can I use code-graph-rag without the CLI?

Yes. Instantiate the CGRConfig dataclass programmatically with your desired parameters and pass it to the RAGEngine class imported from codebase_rag/rag_engine.py. This approach bypasses CLI argument parsing and is suitable for integrating the framework into larger Python applications.

How do I change the embedding model?

Use the --embedder-model CLI flag (e.g., --embedder-model text-embedding-ada-002) or set the corresponding attribute on the CGRConfig object before initializing the engine. The embedder logic in codebase_rag/embedder.py dispatches to the selected provider based on this value.

Where is the configuration schema defined?

The configuration schema is defined by Pydantic models in codebase_rag/workspaces/models.py, primarily within the CGRConfig class. This model aggregates settings from environment variables and CLI flags, performing validation before the pipeline executes in codebase_rag/main.py.

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