# How code-review-graph Handles Multi-Repository Scenarios: A Complete Guide

> Learn how code-review-graph manages multi-repository setups using a registry, isolated graphs, and a watch daemon for unified cross-repo queries. Explore the complete guide.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-08-13

---

**code-review-graph handles multi-repository scenarios through a lightweight registry system that maintains isolated graph databases per repository while enabling unified cross-repository queries via MCP tools and a watch daemon that synchronizes all registered codebases.**

The tirth8205/code-review-graph project is designed to scale from single-repository analysis to complex multi-repository environments. Whether you are working with monorepos, git worktrees, or dozens of independent repositories, the system provides specific mechanisms to index, query, and maintain code graphs across your entire development landscape. This article examines the architectural decisions and implementation details that enable robust multi-repository support.

## Repository Registry Architecture

At the heart of multi-repository support lies a lightweight **registry** stored in `~/.code-review-graph/registry.json`. This JSON file maintains absolute paths and optional aliases for every repository you register, creating a centralized catalog without moving or altering your source code.

The registry is consumed by MCP tools defined in [`code_review_graph/tools/registry_tools.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/registry_tools.py). Specifically, `list_repos_tool` queries this file to display all tracked repositories, while `cross_repo_search_tool` iterates across registered entries to execute distributed queries. When you register a repository using the CLI, the system captures the absolute path and optional alias, making it accessible for cross-repo operations without requiring you to specify full paths repeatedly.

## Monorepo and Git Worktree Support

The system distinguishes between **monorepos**, **git worktrees**, and multiple independent repositories, applying different isolation strategies for each.

**Monorepos** are handled by detecting the repository root through git traversal (walking up to the nearest `.git` directory). The graph is built at the root level using only tracked files from `git ls-files`, automatically excluding git-ignored artifacts. Users can further prune the graph using a `.code-review-graphignore` file or target specific sub-directories by passing `--repo <path>` to any command.

**Git worktrees** receive special treatment in [`docs/FAQ.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/FAQ.md) (lines 225-229). Each worktree is recognized as its own repository root and receives an isolated `.code-review-graph/graph.db` file. This ensures the graph always reflects the specific checkout state of that worktree. Sharing one database across worktrees at different commits is explicitly not supported. You can override the data directory location using `--data-dir` or the `CRG_DATA_DIR` environment variable if you need custom storage paths.

## Cross-Repository Search Implementation

Cross-repository search is implemented in [`code_review_graph/tools/registry_tools.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/registry_tools.py) through the `cross_repo_search_func` function (registered as `cross_repo_search_tool`). The implementation spans lines 49-66 for the function signature and lines 70-84 for the repository iteration logic.

When invoked, the function:
1. Reads all entries from `~/.code-review-graph/registry.json`
2. Iterates over each registered repository
3. Runs `hybrid_search` on each individual graph database
4. Tags results with `repo` and `repo_path` metadata
5. Merges results while preserving per-repository ranking
6. Returns a unified result set to the caller

This design maintains query performance by searching isolated databases in parallel while providing a seamless aggregated view of your codebases.

## Watch Daemon for Multi-Repo Orchestration

Keeping multiple repository graphs up-to-date is handled by a **watch daemon** implemented in [`code_review_graph/daemon.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/daemon.py). The daemon orchestrates graph maintenance across your entire registry without manual intervention.

The daemon configuration resides in `~/.code-review-graph/watch.toml`. Upon startup, the daemon:
- Loads configuration (lines 44-51)
- Registers each configured repository in the global registry (lines 70-78)
- Builds initial graphs if they do not exist (lines 84-92)
- Spawns a `code-review-graph watch` child process for each repository
- Performs periodic health checks to restart dead watchers

You can control the daemon through the CLI:

```bash

# Start the multi-repo watch daemon

crg-daemon start

# or

code-review-graph daemon start

# Add a repository while the daemon is running

crg-daemon add ~/projects/cli --alias cli-tool

# Check daemon status

crg-daemon status

```

When adding a repository via `crg-daemon add`, the system registers the repo, builds an initial graph if missing, spawns a new watch child, and updates its persisted state file at `~/.code-review-graph/daemon-state.json`.

## CLI Commands for Managing Multiple Repositories

The CLI provides comprehensive commands for multi-repository workflows, documented in [`docs/COMMANDS.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/COMMANDS.md) (lines 48-61).

Register independent repositories to build your searchable knowledge base:

```bash

# Register repositories (aliases optional)

code-review-graph register ~/projects/api
code-review-graph register ~/projects/web --alias web-frontend

# List registered repositories

code-review-graph repos

```

Execute cross-repository searches that span your entire registry:

```bash

# Find every function named "login" across all repos

code-review-graph cross-repo-search "login" --kind Function

```

Results include repository metadata:

```json
{
  "results": [
    {
      "name": "login",
      "repo": "api",
      "repo_path": "/home/user/projects/api",
      "score": 0.95
    },
    {
      "name": "login",
      "repo": "web-frontend",
      "repo_path": "/home/user/projects/web",
      "score": 0.92
    }
  ]
}

```

Query specific repositories while maintaining registry context:

```bash
code-review-graph query-graph --pattern callers_of --target login --repo ~/projects/api

```

## Summary

- **Registry-based architecture**: The `~/.code-review-graph/registry.json` file maintains a lightweight catalog of all repositories with their paths and aliases.
- **Isolated graph databases**: Each repository maintains its own `graph.db` file, ensuring clean separation between codebases and worktrees.
- **Cross-repo search**: The `cross_repo_search_tool` in [`code_review_graph/tools/registry_tools.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/registry_tools.py) executes parallel searches across all registered repositories and merges results with proper metadata tagging.
- **Automated synchronization**: The daemon in [`code_review_graph/daemon.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/daemon.py) monitors all registered repositories, rebuilding graphs automatically as code changes.
- **Flexible CLI**: Commands like `register`, `repos`, `cross-repo-search`, and `daemon` provide complete control over multi-repository workflows.

## Frequently Asked Questions

### How does code-review-graph distinguish between monorepos and multiple independent repositories?

Monorepos are detected by walking up the directory tree to the nearest `.git` folder and indexing only tracked files via `git ls-files`. For multiple independent repositories, you explicitly register each root path using `code-review-graph register`, which stores entries in `~/.code-review-graph/registry.json`. The system treats these as distinct graph databases while allowing cross-repo search through the MCP tools.

### Can I share a single graph database between git worktrees?

No. According to the implementation in [`docs/FAQ.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/FAQ.md) (lines 225-229), sharing one database across worktrees at different commits is not supported. Each worktree is recognized as its own repository root and receives its own `.code-review-graph/graph.db` file to ensure the graph accurately reflects the specific checkout state of that worktree.

### What happens when I add a repository to a running daemon?

When you execute `crg-daemon add <path> --alias <name>`, the daemon registers the repository in the global registry, builds an initial graph if one does not exist, spawns a new `code-review-graph watch` child process for that repository, and updates the persisted state file at `~/.code-review-graph/daemon-state.json`. The new repository becomes immediately available for cross-repo searches without requiring a daemon restart.