# How to Perform a Clean Rebuild of the Code Graph in code-graph-rag

> Learn how to perform a clean rebuild of the code graph in code-graph-rag. Delete the graph.json cache and run cgr build for a fresh parse of your source tree.

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

---

**To perform a clean rebuild of the code graph, delete the existing [`graph.json`](https://github.com/vitali87/code-graph-rag/blob/main/graph.json) cache file and run `cgr build` to force a fresh parse of the entire source tree.**

The `vitali87/code-graph-rag` repository maintains a serialized JSON representation of your codebase to accelerate semantic queries and relationship traversal. When source files change significantly or the index becomes stale, you must perform a clean rebuild of the code graph to ensure the cached structure reflects the current repository state.

## Understanding the Graph Cache Architecture

The system persists the parsed code graph to disk as a JSON file that the `GraphLoader` class consumes. In [`codebase_rag/graph_loader.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py), the `load()` method (lines 48-55) attempts to read the file located at `self.file_path`. If this file is missing, the loader raises a `FileNotFoundError`, which signals the CLI or API to regenerate the graph from scratch by re-parsing all supported source files.

The CLI entry point in [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py) orchestrates this regeneration when it detects a missing cache, walking the repository tree, extracting symbols, and writing a new [`graph.json`](https://github.com/vitali87/code-graph-rag/blob/main/graph.json) file.

## Step-by-Step Clean Rebuild Process

A clean rebuild requires two deterministic actions: removing the stale cache and invoking the build pipeline.

### Delete the Existing Cache File

Remove the JSON cache (default name [`graph.json`](https://github.com/vitali87/code-graph-rag/blob/main/graph.json) in the repository root):

```bash
rm -f graph.json

```

If you configured a custom path via the API or environment variables, adjust the filename accordingly. For programmatic deletion, use standard library functions:

```python
import os
GRAPH_PATH = "graph.json"
if os.path.exists(GRAPH_PATH):
    os.remove(GRAPH_PATH)

```

### Trigger a Fresh Build

Invoke the bundled CLI to rebuild the graph from the source tree:

```bash
cgr build

```

Alternatively, use the module invocation:

```bash
python -m codebase_rag.graph_loader --build

```

When the CLI executes, it detects the missing cache file, catches the `FileNotFoundError` from `GraphLoader.load()`, and proceeds to re-index the codebase. The process parses every supported language file, reconstructs symbol relationships, and emits a fresh [`graph.json`](https://github.com/vitali87/code-graph-rag/blob/main/graph.json) containing the updated nodes and edges.

## Programmatic Rebuild Using the Python API

You can force a clean rebuild within Python by deleting the cache before instantiating the loader. The `load_graph` function or `GraphLoader` constructor calls `load()` internally, which automatically triggers a rebuild when the cache is absent.

```python
from codebase_rag.graph_loader import GraphLoader, load_graph
import os

GRAPH_PATH = "graph.json"

# 1. Delete any previous graph cache

if os.path.exists(GRAPH_PATH):
    os.remove(GRAPH_PATH)

# 2. Instantiate loader – triggers fresh build due to missing cache

loader: GraphLoader = load_graph(GRAPH_PATH)

# 3. Verify the new graph structure

print(f"Nodes: {len(loader.nodes)}")
print(f"Relationships: {len(loader.relationships)}")

```

This pattern guarantees that `loader.nodes` and `loader.relationships` reflect the current source state rather than stale cached data.

## CLI-Based Rebuild Workflow

For command-line workflows, combine file removal with the build command:

```bash

# Clean any old graph file

rm -f graph.json

# Rebuild the graph with progress output

cgr build

```

The CLI outputs progress indicators during the process:

```

[INFO] Loading graph…          (no file found – starting fresh)
[INFO] Parsing 5 000 source files…
[INFO] Indexed 8 000 relationships…
[INFO] Graph successfully written to graph.json

```

This confirms that the system detected the missing cache, performed a full re-parse, and persisted the new graph to disk.

## Summary

- **Delete the cache**: Remove [`graph.json`](https://github.com/vitali87/code-graph-rag/blob/main/graph.json) (or your configured cache path) to invalidate the existing graph.
- **Rebuild**: Run `cgr build` or instantiate `GraphLoader` via the API to trigger a fresh parse of the source tree.
- **Verification**: Check `loader.nodes` and `loader.relationships` counts or review CLI output to confirm the rebuild succeeded.
- **Source files**: The rebuild logic resides in [`codebase_rag/graph_loader.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py) (loading/parsing) and [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py) (orchestration).

## Frequently Asked Questions

### Where does code-graph-rag store the graph cache?

By default, the repository stores the serialized graph in a file named [`graph.json`](https://github.com/vitali87/code-graph-rag/blob/main/graph.json) in the project root. The `GraphLoader` class reads this path from `self.file_path` as implemented in [`codebase_rag/graph_loader.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py). You can specify alternative paths when instantiating the loader programmatically.

### What happens if I rebuild without deleting the old cache?

If the cache file exists, `GraphLoader.load()` reads the existing JSON instead of raising `FileNotFoundError`, causing the system to use stale data. To ensure a truly clean rebuild, you must delete the file first to force the parser to traverse the source tree and regenerate the graph from scratch.

### Can I rebuild the graph programmatically without using the CLI?

Yes. Delete the cache file using `os.remove()` and then call `load_graph()` or instantiate `GraphLoader` directly. The constructor invokes `load()`, which detects the missing file and automatically rebuilds the graph by re-parsing the codebase, identical to the CLI behavior.

### How do I verify that the clean rebuild succeeded?

After rebuilding, inspect the `nodes` and `relationships` attributes on your `GraphLoader` instance to confirm they contain the expected counts, or check the CLI output for confirmation messages like "Graph successfully written to graph.json". You can also review the timestamp on [`graph.json`](https://github.com/vitali87/code-graph-rag/blob/main/graph.json) to ensure it reflects the recent build time.