How to Contribute to the code-graph-rag Project: A Step-by-Step Guide

Fork the repository, install dependencies with pip install -r requirements.txt, run pytest -q to verify the test suite, then submit a PR targeting main with Conventional Commits formatting.

The code-graph-rag project is an open-source Python library that transforms codebases into graph structures for Retrieval-Augmented Generation (RAG). If you want to contribute to code-graph-rag, understanding its modular architecture and established workflow will help you submit changes that merge smoothly. This guide walks through the complete contribution process based on the vitali87/code-graph-rag source code.

Project Architecture Overview

The codebase splits into two main areas: the core package (codebase_rag/) containing graph-building logic, and supporting modules for CLI operations, configuration, and evaluation.

Core Components

Component	Responsibility	Source File
Schema Builder	Generates GraphQL-style schema describing code entities and relationships	codebase_rag/schema_builder.py
Graph Loader	Loads persisted graphs (Neo4j, DuckDB) and provides traversal APIs	codebase_rag/graph_loader.py
Parser Loader	Dynamically discovers and registers language-specific parsers	codebase_rag/parser_loader.py
Embedder	Wraps vector-store backends with caching for semantic search	codebase_rag/embedder.py
Dead Code Detector	Analyzes call-graph reachability	codebase_rag/dead_code.py
CLI	Orchestrates graph construction, updates, and queries via the cgr command	codebase_rag/cli.py

Setup Your Development Environment

To contribute to code-graph-rag, start with a proper local setup:

# Clone your fork

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

# Create and activate virtual environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies

pip install -r requirements.txt

# Install pre-commit hooks (enforces PEP 8 style)

pre-commit install

Verify your installation by running the test suite:

pytest -q

All tests must pass before you begin making changes.

Where to Make Changes

The project follows strict organizational conventions. Direct your contributions to the appropriate location:

• New language parsers → codebase_rag/parsers/ (see java_l1.py, go_l1.py as templates)
• Graph traversal fixes → codebase_rag/graph_loader.py
• Schema modifications → codebase_rag/schema_builder.py
• CLI features → codebase_rag/cli.py
• Documentation → docs/ directory and README.md

Practical Contribution Examples

Adding a New Language Parser

Create a parser module in codebase_rag/parsers/:

# codebase_rag/parsers/rust_parser.py

from .base import BaseParser

class RustParser(BaseParser):
    language = "rust"

    def parse(self, source_path: str):
        # Implement AST-Grep or tree-sitter parsing for Rust

        ...

Then register it in parser_loader.py:

from .rust_parser import RustParser

ParserRegistry.register(RustParser())

Extending the Graph Schema

Modify codebase_rag/schema_builder.py to add new relationship types:

def add_dead_code_edge(self, src_node, dst_node):
    """Create a DEAD_CODE edge if dst_node is unreachable from entry point."""
    self.graph.add_edge(src_node, dst_node, type="DEAD_CODE")

Testing Semantic Search Locally

Run queries against your graph build:

cgr query \
  --graph-path ./graph.db \
  --question "How does the caching layer work?" \
  --top-k 5

Pull Request Workflow

Follow this sequence when preparing your contribution to code-graph-rag:

1. Create a descriptive branch: git checkout -b feature/graph-loader-optimisation

2. Make localized changes with corresponding test coverage in evals/

3. Run quality checks:

pre-commit run --all-files
pytest -q

4. Commit using Conventional Commits:

feat(parser): add Rust AST-Grep support
fix(loader): resolve Neo4j connection pooling issue
docs: update embedding configuration examples

5. Push and open a PR targeting the upstream main branch

The PR template (from docs/contributing.md) requires:

• Short description of changes
• Testing methodology
• Any new dependencies

Review Process

Once submitted, your PR triggers:

• Automated test suite execution
• Style and linting checks
• Optional Claude-code review workflow (.github/workflows/claude-code-review.yml)

Address reviewer feedback promptly, rebasing against main if needed. Maintainers merge after CI passes and approvals are complete.

Key Reference Files

File	Purpose
README.md	Project overview, quick-start, contributor entry point
docs/contributing.md	Full contribution guidelines and PR template
codebase_rag/cli.py	Command-line interface implementation
evals/semantic_search.py	Reference test implementation for semantic search features

Summary

• Fork and clone the vitali87/code-graph-rag repository
• Install dependencies and pre-commit hooks before coding
• Target specific modules: parsers go in codebase_rag/parsers/, graph logic in graph_loader.py or schema_builder.py
• Add tests under evals/ following existing language-specific templates
• Use Conventional Commits and run pre-commit run --all-files before pushing
• Reference issues in PR descriptions and complete the template checklist

Frequently Asked Questions

What testing framework does code-graph-rag use?

The project uses pytest. Run pytest -q from the repository root. Tests are organized under the evals/ directory, with files like evals/semantic_search.py and language-specific evaluators (java_l1.py, go_l1.py) serving as templates for new contributions.

Does the project require specific Python dependencies for graph databases?

Yes. The codebase_rag/graph_loader.py module supports multiple backends including Neo4j and DuckDB. Install the appropriate driver packages via requirements.txt. The parser loader dynamically registers components, so optional dependencies are loaded only when their corresponding backends are configured.

How do I test my parser changes before submitting a PR?

Add unit tests under evals/ following the pattern in existing language eval files. You can also run the full pipeline locally: build a test graph with cgr build, then query it with cgr query --graph-path ./graph.db --question "test query". The pre-commit hooks and pytest -q must pass before your PR will be reviewed.

What happens if the automated Claude-code review suggests changes?

The .github/workflows/claude-code-review.yml workflow provides optional AI-assisted feedback. Treat these suggestions as advisory—human maintainers make final review decisions. Address legitimate issues, push fixes to your branch, and the workflow will re-run automatically.

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