How to Add a Project to the Global Graphify Graph: CLI and Python API Guide

Use the global_add function in graphify/global_graph.py or run graphify global add <path> --as <tag> to merge a project graph into the global knowledge graph, which automatically handles validation, namespacing, deduplication, and manifest updates.

Graphify maintains a centralized global knowledge graph that aggregates individual project graphs into a unified representation for cross-repository analysis. Adding a project to the global Graphify graph updates this centralized structure and records the operation in a manifest file, enabling powerful code intelligence across your entire codebase. According to the Graphify-Labs/graphify source code, this process is handled entirely by the global_add function.

Understanding the Global Graph Architecture

The global graph serves as a centralized repository that aggregates multiple project-specific graphs stored in individual repositories. Unlike isolated project graphs, the global graph persists in your home directory at ~/.graphify/global-graph.json with metadata tracked in ~/.graphify/global-manifest.json.

When you add a project, Graphify performs intelligent merging that namespaces nodes to prevent collisions while deduplicating external library references. This architecture ensures that projects remain isolated through prefixed identifiers while shared dependencies are unified to avoid redundancy.

The global_add Function Implementation

The core logic resides in graphify/global_graph.py within the global_add function. This function orchestrates the entire ingestion pipeline, returning a summary dictionary containing the repository tag, counts of nodes added and removed, and whether the operation was skipped due to unchanged content.

Supporting utilities located in companion modules handle specific concerns:

• graphify/build.py: Provides prefix_graph_for_global for namespacing node IDs and prune_repo_from_graph for removing stale entries
• graphify/security.py: Supplies check_graph_file_size_cap to enforce file size limits and prevent resource exhaustion

Step-by-Step Ingestion Process

When you invoke global_add, Graphify executes a nine-step pipeline to safely integrate your project:

1. Validate the source graph file

   The system first checks that the graph file exists and does not exceed size limits using check_graph_file_size_cap from the security module.

2. Load the global manifest

   Graphify reads ~/.graphify/global-manifest.json to check for existing entries, or creates a fresh manifest if this is the first addition.

3. Detect content changes

   The function computes a SHA-256 hash of the source graph. If this hash matches the stored hash in the manifest, the operation skips to avoid redundant processing.

4. Read and normalize the graph

   The source JSON is parsed, with legacy "edges" fields automatically normalized to "links" for consistency, and loaded into a NetworkX graph structure.

5. Prefix node IDs for isolation

   All node IDs are namespaced with the repository tag using prefix_graph_for_global to prevent ID collisions between projects.

6. Prune stale nodes

   Any nodes previously added under the same repository tag are removed from the global graph using prune_repo_from_graph to ensure clean updates.

7. Deduplicate external libraries

   Nodes lacking a source_file but possessing a label (indicating external dependencies) are merged with existing global nodes of the same label to prevent duplication.

8. Merge the prefixed graph

   New nodes and rewired edges are inserted into the global graph, respecting the deduplication map established in the previous step.

9. Persist changes

   The updated global graph is serialized to ~/.graphify/global-graph.json, and the manifest is updated with the new hash, path, and node/edge counts.

Programmatic and CLI Usage

You can add projects to the global graph either through the Python API or the command line interface.

Python API

Import global_add from graphify.global_graph and provide a Path object and repository tag:

from pathlib import Path
from graphify.global_graph import global_add

# Add a new project graph

result = global_add(
    source_path=Path("my-project/graph.json"),
    repo_tag="my-project"
)
print(result)

# → {'repo_tag': 'my-project', 'nodes_added': 124, 'nodes_removed': 0, 'skipped': False}

Command Line Interface

The CLI provides a straightforward interface for manual operations:

graphify global add ./my-project/graph.json --as my-project

Both methods return equivalent results and update the global state atomically.

Summary

• The global_add function in graphify/global_graph.py handles the complete ingestion pipeline when adding a project to the global Graphify graph.
• The process validates file sizes, checksums content for idempotency, namespaces nodes with repository tags, and deduplicates external dependencies.
• Global state persists to ~/.graphify/global-graph.json with metadata tracked in ~/.graphify/global-manifest.json.
• Both programmatic (global_add()) and CLI (graphify global add) interfaces provide identical functionality.

Frequently Asked Questions

What happens if I try to add the same project twice?

Graphify computes a SHA-256 hash of the source graph and compares it against the stored hash in the manifest. If the hashes match, the operation returns immediately with "skipped": true and makes no changes to the global graph.

How does Graphify prevent node ID collisions between different projects?

Before merging, the prefix_graph_for_global function in graphify/build.py namespaces all node IDs with the repository tag. This ensures that main.py from "project-a" and main.py from "project-b" remain distinct entities in the global graph.

Where does Graphify store the global graph?

The serialized global graph resides at ~/.graphify/global-graph.json in your home directory, while the manifest tracking repository hashes, paths, and statistics is stored at ~/.graphify/global-manifest.json.

Can I update an existing project without manually removing it first?

Yes. The global_add function automatically calls prune_repo_from_graph to remove any stale nodes belonging to the same repository tag before inserting the new graph. This ensures clean updates without requiring manual deletion steps.

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