How the Multi-Repo Registry Works in code-review-graph: Cross-Project Code Review Queries

The multi-repo registry in code-review-graph is a user-scoped JSON catalog stored at ~/.code-review-graph/registry.json that maps repository paths to optional aliases, enabling the CLI to execute queries across multiple independent codebases by aggregating results from each registered repository's local graph database.

The code-review-graph tool from the tirth8205/code-review-graph repository provides a lightweight multi-repo registry that allows developers to index and query code review relationships across many independent projects. Instead of isolating analysis to a single repository, this registry acts as a central catalog that points the CLI to multiple per-repo graph databases. By maintaining a user-specific JSON file in the home directory, the tool enables seamless cross-project searches without modifying individual repository internals.

Registry Location and Format

The registry persists as a JSON file located at ~/.code-review-graph/registry.json according to the documentation in docs/TROUBLESHOOTING.md [L69]. Each entry in this object maps a repository path—or an optional alias—to the root directory of a registered project. This simple structure allows the CLI to resolve locations without embedding absolute paths into the tool's configuration.

When loaded, the registry provides a deterministic list of paths that the cross-repo search logic iterates over during query execution.

Registering and Managing Projects

You populate the registry using the code-review-graph CLI. The register command accepts a path and appends it to the JSON catalog, while unregister removes entries by path or alias.

As documented in README.md [L366-L368], the workflow follows this pattern:

# Register a repository by absolute path

code-review-graph register /path/to/my-service

# Remove a registration using its path or alias

code-review-graph unregister /path/to/my-service

# Or using an alias if defined

code-review-graph unregister my-service

The registry logic validates that each entry points to a genuine repository root—including Git or SVN work-trees—before acceptance, as noted in CHANGELOG.md [L455-L456]. This prevents invalid paths from polluting the catalog and ensures the tool can locate the internal .code-review-graph/graph.db file within each project.

Environment Variable Overrides

You can override the default storage behavior using the CRG_DATA_DIR environment variable. As detailed in CHANGELOG.md [L671-L673], this variable influences path resolution for both the per-repo databases and how the registry resolves repository locations.

Executing Cross-Repository Queries

When you invoke a command that supports cross-repo scanning—such as code-review-graph search or the crossRepoSearch API—the client performs the following steps:

1. Loads the registry from ~/.code-review-graph/registry.json.
2. Iterates over every recorded repository path.
3. Opens the local graph database (.code-review-graph/graph.db) found in each repo root.
4. Executes the query against each individual graph.
5. Merges results into a single unified view.

This aggregation happens transparently. For example, searching for callers of a specific function across all registered projects returns a combined result set:

import { crossRepoSearch } from "code-review-graph";

(async () => {
  const results = await crossRepoSearch({
    query: "my_module.my_function",
    kind: "CALLERS_OF",
  });
  console.log(results); // Aggregates callers from every registered repo
})();

Internally, the registry loading mechanism resembles this simplified implementation:

import * as fs from "node:fs";
import * as os from "node:os";

function loadRegistry() {
  const regPath = `${os.homedir()}/.code-review-graph/registry.json`;
  if (!fs.existsSync(regPath)) return {};
  return JSON.parse(fs.readFileSync(regPath, "utf-8"));
}

Because the registry is user-scoped, stored in the home directory rather than within any specific repository, each developer maintains an independent catalog that does not interfere with teammates' configurations. The registry merely points to existing per-repo databases; it never modifies the internal graph files or storage structures of the individual projects.

Summary

• The multi-repo registry is a JSON file at ~/.code-review-graph/registry.json that catalogs repository paths and aliases.
• Use code-review-graph register <path> and unregister <id> to manage entries as documented in README.md [L366-L368].
• Cross-repo queries load the registry, iterate over each path, query local .code-review-graph/graph.db files, and merge results.
• The registry is user-scoped and isolated per developer, supporting Git and SVN work-tree validation.
• Override default paths using the CRG_DATA_DIR environment variable per CHANGELOG.md [L671-L673].

Frequently Asked Questions

Where is the multi-repo registry stored on disk?

The registry resides at ~/.code-review-graph/registry.json in the user's home directory. This location is consistent across platforms and is referenced in docs/TROUBLESHOOTING.md [L69]. The file contains a JSON object mapping repository paths to optional aliases.

Can I use the multi-repo registry with monorepos or work-trees?

Yes. The registry validation logic explicitly supports Git and SVN work-trees, ensuring that each entry points to a genuine repository root before acceptance. According to CHANGELOG.md [L455-L456], the tool validates paths to prevent invalid registrations, making it compatible with complex repository layouts including monorepos.

How does cross-repo search handle conflicting node IDs across projects?

The crossRepoSearch API treats each registered repository as an isolated namespace. When aggregating results, the tool maintains the provenance of each match by including repository metadata in the returned dataset. This allows you to distinguish between identical function names in different codebases while presenting a unified view of the relationships.

What happens if a registered repository is moved or deleted?

If a registered path no longer exists or lacks the expected .code-review-graph/graph.db file, the cross-repo query logic typically skips that entry or reports an error for that specific repository without failing the entire query. You can clean up stale entries by running code-review-graph unregister <path> to remove invalid mappings from the registry.

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