How to Set Up the Multi-Repo Registry in Code-Review-Graph: A Complete Guide

Set up the multi-repo registry by running code-review-graph register <path> [--alias <name>] to add projects, then use cross-repo-search to query across all registered repositories simultaneously.

The multi-repo registry in Code-Review-Graph enables you to register multiple codebases and execute unified searches across them. This eliminates the need to run separate queries for each project, making it ideal for monorepo setups, microservice architectures, or teams managing several related repositories.

Where the Registry Lives

The registry persists as a JSON file in your home directory:

~/.code-review-graph/registry.json

This location is user-scoped, ensuring isolation between different system accounts and preventing conflicts with system-wide configurations.

Registering a Repository

Add repositories using the CLI registration command. You can reference projects by path, with an optional mnemonic alias for convenience.

# Register with an alias

code-review-graph register /home/user/projects/foo --alias foo

# Register without alias (path becomes the identifier)

code-review-graph register /home/user/projects/bar

Each entry in registry.json follows this structure:

{
  "alias": "foo",
  "path": "/home/user/projects/foo"
}

Aliases are optional but recommended. When omitted, the absolute path serves as the unique identifier for unregistration and search filtering.

Listing Registered Repositories

View all currently registered projects:

code-review-graph list-repos

Expected output format:

alias   path
foo     /home/user/projects/foo
bar     /home/user/other/bar

This command queries the registry file directly and displays entries in tabular form.

Cross-Repo Search Implementation

The cross_repo_search tool—implemented in code_review_graph/tools/registry_tools.py—orchestrates multi-repository queries. Its execution flow:

1. Load registry from ~/.code-review-graph/registry.json
2. Resolve aliases to absolute filesystem paths
3. Instantiate GraphStore for each registered repository
4. Execute query against each store individually
5. Merge results with deduplication on fully-qualified node names
6. Preserve highest-scoring match when duplicates exist

Run a cross-repo search:

code-review-graph cross-repo-search "UserService login"

The search operates across all registered repositories transparently, returning combined results as if querying a single unified graph.

Unregistering Repositories

Remove entries by alias or path:

# By alias

code-review-graph unregister foo

# By absolute path

code-review-graph unregister /home/user/projects/foo

The unregistration command performs an atomic update to registry.json, preventing corruption during concurrent modifications.

Manual Registry Editing

Since registry.json is plain JSON, you can edit it directly:

nano ~/.code-review-graph/registry.json

Structure for multiple entries:

[
  {
    "alias": "frontend",
    "path": "/home/user/projects/web-client"
  },
  {
    "alias": "backend",
    "path": "/home/user/projects/api-server"
  }
]

CLI commands provide atomic updates and validation; manual edits require JSON syntax correctness.

Registry Tool Architecture

The core functionality resides in specific source files:

• code_review_graph/tools/registry_tools.py — Contains cross_repo_search_func and list_repos_func, the MCP tool implementations for registry operations
• code_review_graph/tools/__init__.py — Registers registry-related tools with the MCP framework
• docs/COMMANDS.md — CLI command documentation including register, unregister, list-repos, and cross-repo-search
• docs/FAQ.md — Conceptual overview of multi-repo handling
• docs/TROUBLESHOOTING.md — Registry location guidance and diagnostic steps

Summary

• The multi-repo registry stores configuration in ~/.code-review-graph/registry.json
• Use register with optional --alias to add projects; unregister to remove them
• list-repos displays all registered entries
• cross-repo-search queries all registered repositories with automatic result deduplication
• The registry implementation in registry_tools.py creates temporary GraphStore instances per repository and merges results
• Atomic CLI operations prevent file corruption; manual JSON editing is supported but requires valid syntax

Frequently Asked Questions

What file format does the multi-repo registry use?

The registry uses standard JSON at ~/.code-review-graph/registry.json. Each entry contains alias (string, optional) and path (string, required) fields. The file is user-scoped and readable by any text editor or JSON processor.

Can I use the same alias for multiple repositories?

No. Aliases must be unique within a registry file. Attempting to register a duplicate alias triggers an error. Use descriptive prefixes if project names collide, such as team-frontend and vendor-frontend.

How does cross-repo search handle duplicate symbols across projects?

The cross_repo_search tool in registry_tools.py deduplicates results based on fully-qualified node names. When identical symbols exist in multiple repositories, the implementation preserves the highest-scoring match according to the graph's relevance ranking.

Is the registry required for single-repository usage?

No. The registry is optional and only necessary for multi-repo workflows. Single-repository searches operate directly against project-specific GraphStore instances without registry involvement.

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