Multi-Repo Graphs

Lesson 7 · Learn Graphify · ~10 minutes

Real projects span multiple repositories. A test framework in one repo, application code in another, shared utilities in a third. This lesson covers building cross-repo graphs so your AI agent can navigate between them.

Win

After this lesson, you can give the AI a unified graph that spans multiple repos — so it understands how your test framework connects to the code it tests.

The Global Graph

By default, each graphify . produces a project-local graph. The --global flag also merges the result into a shared graph at ~/.graphify/global-graph.json:

# Build project graph AND merge into global
graphify . --global

Do this for each repo you want in the unified view. The global graph accumulates nodes from every project.

# Check what's in the global graph
graphify global list

When Multi-Repo Matters

You need a cross-repo graph when the AI needs to understand boundaries that span repositories:

A test framework repo consumed by multiple application repos
A shared utilities package imported across services
A monorepo split into separate repos (e.g., after extraction)
Library code you own that downstream repos depend on

Note

For your DocumentDB project, this might mean graphing both the performance test repo and the framework/utilities it imports — so the agent understands the full call chain from test case to assertion helper.

Merging Graphs Manually

If you don't want a persistent global graph, merge two graph files on demand:

# Merge two project graphs into a combined file
graphify merge-graphs \
  ~/project-a/graphify-out/graph.json \
  ~/project-b/graphify-out/graph.json \
  -o combined-graph.json

The merged graph shows cross-repo edges — imports that cross repository boundaries become visible connections.

Graphing External Repos

Need to graph a repo you haven't cloned yet?

# Clone and graph in one step
graphify clone https://github.com/org/shared-framework.git

This clones to a temp directory, extracts the graph, and merges it globally. Useful for quickly adding context about a dependency without keeping a full local checkout.

Working with the Combined Graph

Once you have a multi-repo graph, queries work across boundaries:

# Find path from your test to a framework utility
graphify path "test_min_comparisons" "assertResult" --graph combined-graph.json

# Explain a node in the framework repo
graphify explain "BaseTestCase" --graph ~/.graphify/global-graph.json

In an AI session, load the global graph instead of the project-local one for cross-repo awareness.

Trade-offs

Approach	Size	Freshness	Use case
Project-local graph	Small, focused	Easy to keep fresh	Single-repo tasks
Global graph	Larger	Needs rebuild per repo	Cross-repo navigation
On-demand merge	You control	Point-in-time	Specific investigations

Token Budget

A multi-repo graph is bigger. If your combined graph exceeds 50k tokens, the savings ratio drops. Monitor with graphify benchmark --graph combined-graph.json — if the graph itself is a significant fraction of the codebase tokens, you may be better off with scoped project graphs.

Verify Your Understanding

What does the --global flag do when building a graph?

Makes the graph available to all users on the system
Merges the project graph into a shared graph at ~/.graphify/global-graph.json
Pushes the graph to a remote Neo4j database
Installs the Graphify skill globally for all projects

When should you not use a multi-repo graph?

When repos share common imports or utilities
When the combined graph is so large it negates the token savings
When you're working on a single feature in one repo
Both B and C are valid reasons

Do This Now

Run graphify . --global on your primary project
If you have a second related repo, graph it with --global too
Run graphify global list to confirm both appear
Try graphify path between a node in each repo