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

To perform a clean rebuild of the code graph, delete the existing 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, 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 orchestrates this regeneration when it detects a missing cache, walking the repository tree, extracting symbols, and writing a new 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 in the repository root):

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:

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:

cgr build

Alternatively, use the module invocation:

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 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.

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:

# 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 (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 (loading/parsing) and 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 in the project root. The GraphLoader class reads this path from self.file_path as implemented in 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 to ensure it reflects the recent build time.

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