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

> Add your project to the global Graphify graph using the CLI or Python API. Discover how to easily merge project graphs with automatic validation and deduplication.

- Repository: [Graphify Labs/graphify](https://github.com/Graphify-Labs/graphify)
- Tags: how-to-guide
- Published: 2026-07-16

---

**Use the `global_add` function in [`graphify/global_graph.py`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/build.py)**: Provides `prefix_graph_for_global` for namespacing node IDs and `prune_repo_from_graph` for removing stale entries
- **[`graphify/security.py`](https://github.com/Graphify-Labs/graphify/blob/main/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:

```python
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:

```bash
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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/build.py) namespaces all node IDs with the repository tag. This ensures that [`main.py`](https://github.com/Graphify-Labs/graphify/blob/main/main.py) from "project-a" and [`main.py`](https://github.com/Graphify-Labs/graphify/blob/main/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.