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

> Learn how to contribute to the code-graph-rag project. Fork the repo, install dependencies, run tests, and submit a PR with Conventional Commits for a smooth contribution process.

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

---

**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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/schema_builder.py) |
| **Graph Loader** | Loads persisted graphs (Neo4j, DuckDB) and provides traversal APIs | [`codebase_rag/graph_loader.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py) |
| **Parser Loader** | Dynamically discovers and registers language-specific parsers | [`codebase_rag/parser_loader.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/parser_loader.py) |
| **Embedder** | Wraps vector-store backends with caching for semantic search | [`codebase_rag/embedder.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py) |
| **Dead Code Detector** | Analyzes call-graph reachability | [`codebase_rag/dead_code.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/dead_code.py) |
| **CLI** | Orchestrates graph construction, updates, and queries via the `cgr` command | [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py) |

## Setup Your Development Environment

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

```bash

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

```bash
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`](https://github.com/vitali87/code-graph-rag/blob/main/java_l1.py), [`go_l1.py`](https://github.com/vitali87/code-graph-rag/blob/main/go_l1.py) as templates)
- **Graph traversal fixes** → [`codebase_rag/graph_loader.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py)
- **Schema modifications** → [`codebase_rag/schema_builder.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/schema_builder.py)
- **CLI features** → [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py)
- **Documentation** → `docs/` directory and [`README.md`](https://github.com/vitali87/code-graph-rag/blob/main/README.md)

## Practical Contribution Examples

### Adding a New Language Parser

Create a parser module in `codebase_rag/parsers/`:

```python

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

```python
from .rust_parser import RustParser

ParserRegistry.register(RustParser())

```

### Extending the Graph Schema

Modify [`codebase_rag/schema_builder.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/schema_builder.py) to add new relationship types:

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

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

```bash
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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/.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`](https://github.com/vitali87/code-graph-rag/blob/main/README.md) | Project overview, quick-start, contributor entry point |
| [`docs/contributing.md`](https://github.com/vitali87/code-graph-rag/blob/main/docs/contributing.md) | Full contribution guidelines and PR template |
| [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py) | Command-line interface implementation |
| [`evals/semantic_search.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/graph_loader.py) or [`schema_builder.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/evals/semantic_search.py) and language-specific evaluators ([`java_l1.py`](https://github.com/vitali87/code-graph-rag/blob/main/java_l1.py), [`go_l1.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py) module supports multiple backends including **Neo4j** and **DuckDB**. Install the appropriate driver packages via [`requirements.txt`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/.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.