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

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

# 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 (lines 48-61).

Register independent repositories to build your searchable knowledge base:

# 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:

# Find every function named "login" across all repos

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

Results include repository metadata:

{
  "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:

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 executes parallel searches across all registered repositories and merges results with proper metadata tagging.
• Automated synchronization: The daemon in 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 (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.

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