@gaodes/pi-graphify

Turn any folder of files (code, docs, papers, images, video) into a queryable knowledge graph with community detection, an honest audit trail, and three outputs: interactive HTML, GraphRAG-ready JSON, and a plain-language GRAPH_REPORT.md.

Source · npm

Inspired by graphify — the AI coding assistant skill. This extension wraps graphify's Python CLI for native Pi integration.

It also bundles a graphify skill (skills/graphify/SKILL.md) for full-pipeline orchestration. Use /skill:graphify when you want the guided multi-step workflow; use the tools and /graphify command for fast operational calls.

Tools

| Tool | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | graphify_build | Build a knowledge graph from a directory (full pipeline: detect → extract → cluster → visualize) | | graphify_query | Query the graph — BFS for broad context, DFS for tracing specific paths | | graphify_path | Find the shortest path between two concepts in the graph | | graphify_explain | Plain-language explanation of a node — everything connected to it | | graphify_add | Fetch a URL and add it to the corpus, then update the graph | | graphify_update | Incremental update — re-extract only changed files | | graphify_watch | Watch a directory for changes, auto-rebuild graph on code edits | | graphify_cluster | Re-run community detection on an existing graph (no re-extraction) | | graphify_extract | Headless LLM extraction for CI — defaults to deepseek; also supports claude, kimi, openai, gemini, ollama, bedrock, claude-cli | | graphify_export_callflow | Generate self-contained Mermaid architecture/call-flow HTML from graph.json | | graphify_upgrade | Check for and install graphifyy CLI updates via uv |

Commands

| Command | Description | | ----------- | ------------------------------------------------------------------ | | /graphify | Single entry point with autocomplete for all subcommands and flags |

Subcommands and flags

/graphify <path>                              # build graph (full pipeline, semantic backend defaults to deepseek)
/graphify <path> --mode deep                  # thorough extraction, richer INFERRED edges
/graphify <path> --update                     # incremental — re-extract only changed files
/graphify <path> --cluster-only               # rerun clustering on existing graph
/graphify <path> --no-viz                     # skip visualization, just report + JSON
/graphify <path> --obsidian                   # generate Obsidian vault
/graphify <path> --svg                        # export graph.svg
/graphify <path> --graphml                    # export for Gephi / yEd
/graphify <path> --neo4j                      # generate cypher.txt for Neo4j
/graphify <path> --callflow                   # generate callflow architecture HTML

/graphify query "<question>"                  # BFS traversal — broad context
/graphify query "<question>" --dfs            # DFS — trace a specific path
/graphify query "<question>" --budget 1500    # cap answer at N tokens
/graphify path "ConceptA" "ConceptB"          # shortest path between two concepts
/graphify explain "ConceptName"               # plain-language explanation of a node
/graphify add <url>                           # fetch URL, save to ./raw, update graph
/graphify add <url> --author "Name"           # tag who wrote it
/graphify update <path>                       # incremental update
/graphify watch <path>                        # watch folder, auto-rebuild on changes
/graphify cluster                             # rerun clustering on existing graph
/graphify hook install                        # install git hooks for auto-rebuild
/graphify hook uninstall                      # remove git hooks
/graphify hook status                         # check hook status
/graphify extract <path>                      # headless LLM extraction for CI
/graphify extract <path> --backend claude     # specify LLM backend
/graphify extract <path> --backend kimi       # Kimi AI backend
/graphify extract <path> --backend openai     # OpenAI backend
/graphify extract <path> --backend gemini     # Google Gemini backend
/graphify extract <path> --backend ollama     # Ollama (local) backend
/graphify extract <path> --backend bedrock    # AWS Bedrock backend
/graphify extract <path> --max-workers 4      # limit parallel workers
/graphify extract <path> --token-budget 4096  # cap tokens per LLM call
/graphify extract <path> --api-timeout 300    # HTTP timeout in seconds
/graphify extract <path> --backend deepseek   # DeepSeek backend (default)
/graphify extract <path> --backend claude-cli  # route through Claude Code CLI
/graphify extract <path> --resolution 2.0      # Leiden clustering resolution
/graphify extract <path> --exclude-hubs 0.05   # exclude top-P% hub nodes
/graphify extract <path> --exclude '*.min.js'  # runtime exclusion patterns
/graphify upgrade                            # check for graphifyy CLI updates
/graphify upgrade --install                  # install latest graphifyy version
/graphify uninstall                           # remove graphify from all platforms
/graphify uninstall --purge                   # also delete graphify-out/

Prerequisites

• Python 3.10+
• graphifyy package (auto-installed on first run): pip install graphifyy or uv tool install graphifyy

Install

pi install @gaodes/pi-graphify

Configuration

Key: pi-graphify in prime-settings.json (legacy graphify key auto-migrates on load).

| Setting | Type | Default | Description | | ------------------------------------------ | ---------- | ----------------- | ------------------------------------------------------------------ | | enabled | boolean | true | Enable/disable the extension | | pythonPath | string | "python3" | Path to Python interpreter | | outputDir | string | "graphify-out" | Output directory name | | semanticBackend | string | "deepseek" | Default semantic extraction backend for builds/extracts | | autoContext.enabled | boolean | true | Enable Graphify auto-context hooks | | autoContext.sessionSummary | boolean | true | Inject architecture orientation at session start | | autoContext.augmentSearchResults | boolean | true | Enable Graphify augmentation of tool results (hints + intent-aware suggestions) | | autoContext.intentSuggestions | boolean | true | Generate intent-aware suggested queries in tool-result hints | | autoContext.autoQuery | boolean | false | Run actual graphify queries on high-confidence intents (off by default) | | autoContext.includeReport | boolean | true | Include GRAPH_REPORT.md content in session orientation | | autoContext.includeWiki | boolean | true | Include wiki/index.md in session orientation | | autoContext.reportMaxChars | number | 6000 | Max characters read from report/wiki files | | autoContext.queryBudget | number | 1200 | Budget hint for graphify_query follow-up usage | | autoContext.maxSessionAugments | number | 8 | Max tool-result augmentations per session | | autoContext.maxAugmentChars | number | 1200 | Hard bound on appended context characters | | autoContext.minToolResultLines | number | 8 | Minimum lines in tool result to trigger augmentation | | autoContext.triggerTools | string[] | (see defaults) | Tool names that trigger augmentation | | autoContext.triggerPatterns | string[] | (see defaults) | Input patterns that trigger architecture-level hints |

Auto-context behavior

When graphify-out/graph.json exists in the current project, pi-graphify provides architecture-level context to the agent. This complements GitNexus (which provides symbol-level call-graph intelligence).

• Session orientation — injects a concise [Graphify active] prompt with suggested queries and report summary when sessionSummary is enabled
• Intent-aware tool hints — classifies tool results by intent (broad search, high-value file reads, architecture terms) and appends relevant Graphify suggestions
• Optional auto-query — when autoQuery is enabled, runs bounded graphify query on high-confidence intents (disabled by default to avoid cost/noise)
• Session budgets — enforces max augmentations per session and hard character limits
• Deduplication — caches augmented and empty results to avoid repeated noise

Settings profiles

Quiet — session hint only:

{ "pi-graphify": { "autoContext": { "sessionSummary": true, "augmentSearchResults": false, "autoQuery": false } } }

Balanced (default) — architecture hints without auto-query:

{ "pi-graphify": { "autoContext": { "sessionSummary": true, "intentSuggestions": true, "augmentSearchResults": true, "autoQuery": false, "maxSessionAugments": 8 } } }

Proactive — auto-query on high-confidence intents:

{ "pi-graphify": { "autoContext": { "sessionSummary": true, "intentSuggestions": true, "augmentSearchResults": true, "autoQuery": true, "maxSessionAugments": 12, "maxAugmentChars": 1800 } } }

Graphify vs GitNexus

| Aspect | Graphify | GitNexus | | --------------- | ------------------------------------------ | ----------------------------------------- | | Scope | Architecture, concepts, communities, docs | Symbols, call graphs, execution flows | | Best for | "What is this system made of?" | "What calls this, and what breaks?" | | Augmentation | Session orientation + intent-aware hints | Pre-commit impact analysis + code context | | Trigger | Broad search, overview files, architecture | Code edits, symbol lookups | | Query tools | graphify_query, graphify_explain | gitnexus_query, gitnexus_impact |

Use Graphify when exploring system shape and cross-cutting concepts. Use GitNexus when tracing code paths and assessing change impact.

• This is Pi-native behavior in this extension; the Graphify skill is installed by graphify install --platform pi to the global Pi skills directory (~/.pi/agent/skills/graphify/SKILL.md). Auto-reinstalled on upgrade via graphify_upgrade.
• Auto-context hooks stay idle in projects where <outputDir>/graph.json is missing.

Git tracking policy

The extension's .gitignore ignores the entire graphify-out/ directory. Graph output is regenerated on each build and should not be committed to the repository.

If you want to track graph output for documentation purposes, override in your project's .gitignore:

!graphify-out/
!graphify-out/graph.json

Note: Earlier versions of pi-graphify tracked graphify-out/ files and selectively ignored cache/temp entries. As of v0.1.6, the entire directory is ignored for cleaner repository state.

Reliability

All child-process invocations run through a bounded exec adapter that caps stdout/stderr at 1 MiB by default. This prevents V8 heap exhaustion when graph operations produce multi-MB output — the root cause of the exit-code 32102 (OOM) crash in earlier versions.

Key safety features:

• Output budgets: 256 KiB for queries, 1 MiB for general operations, 2 MiB for JSON parsing
• Thin CLI layer: all graph operations delegate directly to the graphify CLI, avoiding inline Python script overhead and ensuring automatic upstream compatibility
• Signal-death handling: child processes killed by signals are reported as failures (exit code 1), not silent successes
• LRU cache bounding: auto-context augmentation caches cap at 256 entries

Source

• Canonical: ~/agents/primecodex/packages/pi-graphify/
• GitLab: agents/primecodex/packages/pi-graphify
• GitHub: github.com/gaodes/pi-graphify