graphify

name	graphify
description	Build, update, query, and navigate graphify knowledge graphs in pi. Use for codebase/corpus architecture questions, /graphify requests, GRAPH_REPORT.md, graph.json, wiki navigation, graph freshness, clone/merge-graphs, MCP graph access, or turning code/docs/papers/images/audio/video into a persistent graph.

graphify for pi

Use graphify from pi to build and navigate persistent project knowledge graphs.

Graphify upstream target for this skill: safishamsi/graphify v0.8.x. The Python package is graphifyy; the CLI is graphify.

Pi-specific behavior

This package includes a pi extension that makes graphify semi-always-on:

• if graphify-out/GRAPH_REPORT.md exists, pi is reminded to consult it before broad raw search
• if only graphify-out/graph.json exists, use it as the fallback map
• /graphify ... is registered as a pi command that delegates to this skill workflow
• if graphify-out/needs_update exists or code files changed during the session, update guidance should recommend graphify update .

When working on architecture/codebase questions in a project that already has graphify output, read these first:

1. graphify-out/wiki/index.md if present (agent-crawlable wiki)
2. graphify-out/GRAPH_REPORT.md (god nodes, communities, suggested questions)
3. graphify-out/graph.json only when a deeper graph-level inspection is needed
4. Prefer graphify query, graphify path, or graphify explain over broad raw grep

Command map

Build & update

graphify update .                              # Safe incremental update after code edits (AST-only, no LLM needed)
  GRAPHIFY_FORCE=1 graphify update .            # Force rebuild after refactors that delete code
  --no-cluster                                 #   Skip clustering, write raw extraction only
graphify cluster-only .                        # Recluster existing graph and regenerate report
graphify extract <path>                        # Full extraction: AST + semantic LLM pass
  --backend openai                             #   OpenAI-compatible API (OpenRouter, etc.)
  --model <model>                              #   Model to use for semantic pass
  --no-cluster                                 #   Skip clustering, write raw extraction
graphify export wiki                           # Generate agent-crawlable wiki (index.md + articles)
graphify export callflow-html                  # Mermaid architecture/call-flow diagrams
graphify export obsidian                       # Export as Obsidian vault
Note: Wiki export requires a prior `graphify extract .` (with LLM backend) — `graphify update .` alone does not generate the `.graphify_analysis.json` file needed for wiki generation. After running `graphify extract .`, you can export wiki separately or it auto-generates as part of the `/graphify-extract` command (if using the pi extension).
graphify export svg                            # Export graph as SVG
graphify export graphml                        # Export as GraphML (Gephi, yEd)
graphify export neo4j                          # Export Cypher for Neo4j

Query & navigate

graphify query "show the auth flow"            # BFS traversal of graph.json
  --dfs                                        #   Use depth-first instead of breadth-first
  --budget 1500                                #   Cap output at N tokens (default 2000)
graphify path "AuthModule" "Database"          # Shortest path between two nodes
graphify explain "SwinTransformer"             # Node + neighbors explanation
graphify tree                                  # Collapsible D3 tree HTML output

Corpus management

graphify add https://example.com/post          # Fetch URL into corpus and update graph
  --author "Name"                              #   Tag the author
  --contributor "You"                          #   Tag who added it
graphify clone https://github.com/owner/repo   # Clone GitHub repo and graph it
graphify merge-graphs repo1/graph.json repo2/graph.json --out graphify-out/merged-graph.json

Watch & hooks

graphify watch .                               # Auto-rebuild on file changes
graphify hook install                          # post-commit/post-checkout git hooks
graphify hook status                           # Check if hooks are installed
graphify hook uninstall                        # Remove hooks

Utilities

graphify check-update <path>                   # Check if semantic re-extraction is pending (cron-safe)
graphify benchmark [graph.json]               # Measure token reduction vs full-corpus read
graphify save-result --question Q --answer A  # Save Q&A to graph memory for feedback loop
graphify global add <graph.json> --as <tag>   # Add project to cross-repo global graph
graphify global list                          # List repos in global graph

Standard workflows

1. Existing graph: answer graph-first

1. Check for graphify-out/GRAPH_REPORT.md and graphify-out/graph.json.
2. Read GRAPH_REPORT.md first for structure, god nodes, and communities.
3. Use graph edges to choose targeted raw files only when implementation confirmation is needed.
4. For cross-module relationship questions, prefer:
   • graphify query "QUESTION"
   • graphify path "A" "B"
   • graphify explain "NODE"
5. If the graph lacks enough information, say so; do not invent nodes, edges, or source paths.

2. Fresh build

Use this when no graphify-out/ exists or the user explicitly asks to build a graph.

graphify update .

This does an AST-only pass (no LLM cost). It extracts code structure, imports, function calls, and writes graph.json, GRAPH_REPORT.md, and graph.html.

For a large or risky corpus, first inspect scope cheaply:

find . -maxdepth 3 -type f | wc -l
find . -maxdepth 3 -type d \( -name node_modules -o -name .git -o -name dist -o -name build \) -prune -o -type f -print | head -50

If the corpus is huge, ask which subfolder to graph instead of running an expensive broad build. Respect .graphifyignore for exclusions.

After the build, read graphify-out/GRAPH_REPORT.md and summarize only:

• God Nodes (highest-degree concepts)
• Surprising Connections (cross-module edges)
• Suggested Questions

Do not dump the whole report unless asked.

3. Semantic enrichment (optional, uses LLM)

For richer inferred relationships beyond AST structure, run a semantic pass:

# Using pi's auth key for OpenAI-compatible providers (OpenRouter, etc.)
# The extension automatically reads the key from pi's auth storage
graphify extract . --backend openai --model <model-name>

The semantic pass adds INFERRED edges between related concepts, enriches doc/comment understanding, and improves query results. It uses the extraction backend you configure (OpenAI-compatible, Claude, Gemini, etc.).

To check if a semantic pass is pending due to doc/image changes:

graphify check-update .

4. Update after code changes

If code files changed during the session or graphify-out/needs_update exists:

graphify update .

Use update instead of a full rebuild when a graph already exists. It's safe, incremental, and costs zero LLM tokens for code changes.

For clustering-only changes (no code structure changed, just want different communities):

graphify cluster-only .

5. Query, path, and explain

Use graph queries when the user asks how concepts relate, where a flow crosses modules, or why a component exists.

graphify query "show the auth flow"
graphify path "AuthModule" "Database"
graphify explain "DigestAuth"

Answer from the returned subgraph. Cite source files/locations from the query output when present.

For deeper exploration:

graphify query "what connects auth to the database?" --dfs --budget 1500

6. GitHub clone and cross-repo graphs

graphify clone https://github.com/owner/repo
graphify clone https://github.com/owner/repo --branch feature-x

Graphify clones into ~/.graphify/repos/<owner>/<repo> and reuses existing clones. If the user gives /graphify https://github.com/owner/repo, treat the resolved local clone path as the corpus target.

For multiple repos:

graphify clone https://github.com/owner/repo-a
graphify clone https://github.com/owner/repo-b
graphify update ~/.graphify/repos/owner/repo-a
graphify update ~/.graphify/repos/owner/repo-b
graphify merge-graphs \
  ~/.graphify/repos/owner/repo-a/graphify-out/graph.json \
  ~/.graphify/repos/owner/repo-b/graphify-out/graph.json \
  --out graphify-out/cross-repo-graph.json

Merged nodes carry repo metadata so answers can distinguish origins.

7. Add URLs or media

graphify add https://arxiv.org/abs/1706.03762
graphify add https://example.com/article --author "Author" --contributor "Your Name"
graphify add https://youtube.com/watch?v=...   # requires graphifyy video extras

Video/audio transcription requires upstream optional dependencies:

pip install 'graphifyy[video]'

Office/PDF extras may similarly require upstream extras. If a command reports a missing optional dependency, tell the user the exact install hint.

8. MCP graph access

For repeated structured graph queries in a single session:

python -m graphify.serve graphify-out/graph.json

The upstream MCP server exposes tools: query_graph, get_node, get_neighbors, get_community, god_nodes, graph_stats, shortest_path.

Use MCP when you'll ask many graph questions. Use CLI graphify query/path/explain for single focused answers.

9. Watch and git hooks

For long agentic edit sessions:

graphify watch .

Code changes rebuild graph artifacts automatically. Non-code/docs/media changes write graphify-out/needs_update, after which you run a manual graphify update ..

For commit-based refresh:

graphify hook install
graphify hook status
graphify hook uninstall

Verifying the graph

After build or update, check the graph is usable:

graphify query "summary"

Should return god nodes and community structure. If it returns nothing meaningful, the graph may need a rebuild with --force:

GRAPHIFY_FORCE=1 graphify update .

Safety and honesty rules

• Do not read or paste all of graph.json unless it is small and necessary.
• Prefer GRAPH_REPORT.md and query output over broad raw grep.
• Never invent edges, source paths, or ownership from labels alone.
• If a graph artifact gives an exact path, use that exact path.
• If no exact path is present, do one narrow lookup and then read the real file.
• When graph output is stale, say so and run or recommend graphify update ..
• Keep summaries concise and cite graph artifacts clearly.

Output summary pattern

After build/update:

• "I built/updated the graph at graphify-out/."
• "I read graphify-out/GRAPH_REPORT.md."
• "Top god nodes: ..."
• "Surprising connections: ..."
• "Suggested follow-up questions: ..."

After query/path/explain:

• "I queried the graph with graphify query ...."
• "Relevant nodes/edges: ..."
• "Source files cited by the graph: ..."
• "Confidence caveat: EXTRACTED vs INFERRED/AMBIGUOUS where relevant."