Configuration Options for code-graph-rag: Environment Variables, CLI Flags, and Dataclass Settings

Configure code-graph-rag via environment variables for secrets, CLI flags for runtime overrides, and the CGRConfig dataclass for programmatic control.

code-graph-rag is a Python-based framework that constructs a code graph from repositories and enables Retrieval-Augmented Generation (RAG) for querying source code. Understanding the available configuration options allows you to customize embedding providers, vector store backends, and graph construction parameters to match your specific infrastructure requirements.

Configuration Mechanisms Overview

The framework implements a layered configuration strategy defined across three core files: codebase_rag/workspaces/constants.py for environment defaults, codebase_rag/workspaces/cli.py for argument parsing, and codebase_rag/workspaces/models.py for schema validation. These layers cascade from system-level environment variables to explicit code-level settings.

Environment Variables

Sensitive credentials and endpoint URLs are sourced from environment variables declared in codebase_rag/workspaces/constants.py. The system expects these variables to be set before initializing the pipeline:

• OPENAI_API_KEY – Authentication token for OpenAI API access
• VECTOR_STORE_URL – Endpoint URL for vector store providers (Pinecone, Weaviate, or local Qdrant)
• VECTOR_STORE_API_KEY – Optional authentication key depending on the provider

Command-Line Interface Flags

The cgr entry point implemented in codebase_rag/workspaces/cli.py exposes an argparse-based interface that maps arguments to the configuration model. Key flags include:

• --repo – Target repository URL or local path to analyze
• --embedder – Embedding provider selection (e.g., openai)
• --vector-store – Vector database backend (e.g., qdrant)
• --output-dir – Workspace directory for generated graphs and logs (default: ./cgr_workspace)

Programmatic Configuration

For embedded use within larger applications, instantiate the CGRConfig dataclass directly from codebase_rag/workspaces/models.py. The RAGEngine class in codebase_rag/rag_engine.py accepts this configuration object to initialize the pipeline without invoking the CLI.

CLI Flags and Options

The codebase_rag/workspaces/cli.py module parses the following arguments that override default settings:

1. --repo – Specifies the target Git repository URL or local filesystem path
2. --embedder – Selects the embedding provider (options: openai, huggingface)
3. --vector-store – Configures the vector database backend
4. --output-dir – Defines the workspace directory for artifacts
5. --embedder-model – Specifies the model name (e.g., text-embedding-ada-002)
6. --chunk-size – Controls the number of lines per code chunk for embedding
7. --prune-threshold – Sets the minimum edge weight for graph pruning to maintain compactness

Advanced Configuration Parameters

Beyond basic connectivity, fine-tune the graph construction and retrieval behavior through these settings defined in the CGRConfig schema:

• Chunk Size (--chunk-size) – Determines how source code is segmented before embedding. Smaller values increase granularity but require more storage.
• Graph Pruning (--prune-threshold) – Removes low-weight edges from the Neo4j-compatible graph to reduce noise, specified as a float between 0.0 and 1.0.
• Embedding Model (--embedder-model) – Overrides the default model selection for custom embedding providers configured in codebase_rag/embedder.py.

Programmatic Configuration Example

Instantiate the configuration directly when integrating code-graph-rag as a library:

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 Example

Execute the full pipeline via the command line with explicit overrides:

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

This command triggers the sequence defined in codebase_rag/main.py: repository cloning, AST parsing, graph building, embedding generation, and vector store population.

Summary

• Environment variables in constants.py handle secrets and endpoint configuration required for API access
• CLI flags in cli.py provide runtime overrides for repository selection, embedder choice, and output directories
• CGRConfig dataclass in models.py enables type-safe programmatic configuration when embedding the framework
• Advanced parameters like --chunk-size and --prune-threshold control the granularity and density of the generated code graph
• RAGEngine class serves as the primary entry point for executing queries against configured workspaces

Frequently Asked Questions

How do I switch from OpenAI to a local embedding provider?

Modify the --embedder flag to specify your local provider (e.g., huggingface) and update the --embedder-model path accordingly. Ensure the corresponding environment variables for your local service are set in codebase_rag/workspaces/constants.py or passed directly to CGRConfig when using the programmatic interface.

Where does code-graph-rag store the generated graph files?

The framework writes all artifacts to the directory specified by --output-dir (default: ./cgr_workspace). This includes the Neo4j-compatible graph export, embedding caches, and processing logs as orchestrated by codebase_rag/main.py.

Can I configure the vector store connection without environment variables?

Yes. While constants.py defines environment variable names as defaults, you can bypass environment-based configuration by explicitly setting the vector_store_url and vector_store_api_key parameters when constructing a CGRConfig instance programmatically in codebase_rag/workspaces/models.py.

What happens if I don't set the prune threshold?

If --prune-threshold is omitted, codebase_rag/main.py uses the default value defined in CGRConfig, typically retaining all graph edges. This results in a denser graph that may impact query performance but preserves complete relationship mappings from the AST analysis.

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