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

> Learn how the multi-repo registry in code-review-graph enables cross-project code review queries by aggregating data from multiple repositories into a unified graph database.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: deep-dive
- Published: 2026-08-06

---

**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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/README.md) [L366-L368], the workflow follows this pattern:

```bash

# 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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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:

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

```typescript
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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.