How to Explain a Node in the Graphify Graph: A Complete Guide

Run graphify explain "<node-name>" to generate a human-readable description of any code concept stored in the Graphify knowledge graph, including its relationships and annotated lessons.

Graphify, developed by Graphify-Labs, converts your codebase into a persistent knowledge graph stored in the graphify-out/ directory. When you need to understand what a specific class, function, or module represents without reading raw source files, you can explain a node in the Graphify graph to receive a contextual summary. This command leverages the aggregated graph structure to deliver fast, stable descriptions that include hand-written lessons and relationship mappings.

The graphify explain Command Syntax

The explain sub-command is the primary interface for retrieving node descriptions from the Graphify knowledge graph.

Basic Usage

To explain a node, pass the concept name as a quoted argument:

graphify explain "RateLimiter"

This queries the default graph at graphify-out/graph.json and returns a plain-language summary describing the node's type, purpose, and key relationships.

Advanced Options

For custom graph locations or specific output requirements, use the --graph flag:

graphify explain "SwinTransformer" --graph /tmp/custom-graph.json

You can also redirect the output to generate documentation files:

graphify explain "SwinTransformer" > docs/knowledge/SwinTransformer.md

How Node Explanation Works Under the Hood

According to the Graphify-Labs/graphify source code, the explanation process follows a four-stage pipeline that transforms graph data into readable text.

Node Lookup and Resolution

In graphify/cli.py, the explain sub-command first searches the aggregated graph (graphify-out/graph.json) for a node whose label matches the supplied name. When multiple matches exist, the system selects the most specific node, typically prioritizing file-level nodes over broader matches. This resolution ensures you receive the most relevant context for the requested concept.

Neighbour Extraction

Once the target node is identified, Graphify gathers its immediate neighbours by traversing both incoming and outgoing edges. This extraction captures how the node is used, defined, or referenced throughout the codebase, including relationships like calls, imports, defines, and explains.

Reasoning and Summarisation

The graphify/extract.py module plays a critical role in this stage. For each neighbouring node, Graphify retrieves:

• Source location: The specific file and line number where the relationship occurs
• Lesson annotations: Concise, hand-written explanations embedded in source files as comments

If a lesson annotation exists for a neighbour, the system displays it directly. Otherwise, graphify/extract.py falls back to generic descriptions derived from the edge type (e.g., "calls", "imports", "explains"). This hybrid approach combines human-authored context with automated relationship mapping.

Plain-Language Output Generation

The final stage formats the collected data into a structured paragraph that includes:

• The node's type (class, function, file, or module)
• A brief summary or lesson if available
• A list of relevant neighbours with one-sentence rationales for each edge

Because this process operates on the pre-built graph rather than grepping raw source files, results are fast, deterministic, and free of duplicate noise.

Practical Code Examples

Explain a Class and Its Consumers

$ graphify explain "RateLimiter"

# → "RateLimiter is a class that throttles API calls. It is instantiated

#    in `src/utils/api.ts` and referenced by the `AuthService` to ensure

#    we never exceed the provider's request quota."

Explain a Function's Import Chain

$ graphify explain "fetchData"

# → "`fetchData` is an async helper that retrieves JSON from the backend.

#    It is defined in `src/lib/network.ts` and is imported by

#    `src/components/dashboard.tsx` and `src/services/report.ts`."

Generate Documentation from Specific Graph Files

graphify explain "AuthService" --graph ./alternate-graph.json > ./docs/auth-service.md

Key Implementation Files

Understanding the following files helps you customize or debug the explanation process:

• graphify/cli.py: Implements the explain argument parser, node lookup logic, and formatted output printing.
• graphify/serve.py: Provides the HTTP API endpoint /explain that mirrors CLI behavior for web-based integrations.
• graphify/extract.py: Extracts lesson annotations from source files and attaches them to graph nodes during the reasoning phase.
• graphify/querylog.py: Optional logging module that records each explain request for auditing or debugging purposes.
• docs/how-it-works.md: High-level documentation describing the Graphify pipeline and the purpose of node explanations.
• docs/node-summaries-rfc.md: Specification document defining the node-level summary format that explain surfaces.

Summary

• Use graphify explain "<node>" to retrieve human-readable descriptions of any code concept in your knowledge graph.
• The command queries graphify-out/graph.json and resolves the most specific node match when multiple candidates exist.
• Explanations combine lesson annotations (hand-written comments) with edge-derived relationships to provide context.
• The process operates on the aggregated graph, making it faster and more stable than text-based source searching.
• Implementation spans graphify/cli.py for CLI logic, graphify/extract.py for annotation processing, and graphify/serve.py for HTTP API access.

Frequently Asked Questions

How does Graphify choose which node to explain when multiple nodes share the same name?

When multiple nodes match the supplied name, Graphify selects the most specific node, typically prioritizing file-level nodes over broader or more generic matches. This resolution logic in graphify/cli.py ensures you receive the most contextually relevant explanation for the requested concept.

Can I explain a node using a custom graph file instead of the default?

Yes. Use the --graph flag to specify an alternative path: graphify explain "NodeName" --graph /path/to/custom-graph.json. This allows you to generate explanations from historical graph snapshots or independently generated knowledge graphs.

What are "lesson" annotations and how do they appear in explanations?

Lessons are concise, hand-written explanations embedded as comments in your source code and extracted by graphify/extract.py. When present, they appear directly in the explanation output as the primary description of a node or relationship. If no lesson exists, Graphify falls back to generic descriptions based on edge types like calls or imports.

Is there an HTTP API equivalent to the graphify explain command?

Yes. The graphify/serve.py module exposes an /explain endpoint that mirrors the CLI behavior. This allows web-based tools and integrations to request node explanations programmatically without invoking the command line interface.

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