--- name: graphify trigger: /graphify description: > Turn any folder of files — code, docs, papers, images, or video — into a persistent, queryable knowledge graph with entity/relationship extraction, confidence scoring, Louvain community detection, and three outputs: interactive HTML, GraphRAG-ready JSON, and a plain-language GRAPH_REPORT.md. Use when you need to understand a codebase's architecture, trace cross-file relationships, or build a navigable map of a document corpus. user_invocable: true --- > **Public / shared version** — trimmed from a private Claude Code setup and > posted at smereski.com as a reusable pattern. # graphify — files to knowledge graph Turn any folder of code, docs, papers, images, or video into a queryable knowledge graph. Persistent across sessions, honest audit trail (EXTRACTED/INFERRED/AMBIGUOUS), community detection surfaces cross-document connections you wouldn't think to ask about. ## When to use / when NOT to use **Use for:** understanding a codebase's architecture, tracing data flows, mapping relationships across a large document corpus, asking "how does X connect to Y?" across hundreds of files. **Do NOT use for:** questions answerable from the current conversation, a single file you can just read, or general programming knowledge. Building a graph costs tokens — query an existing `graphify-out/` before ever rebuilding. ## Usage ``` /graphify # full pipeline on current directory /graphify # full pipeline on specific path /graphify https://github.com// # clone then run /graphify --mode deep # richer INFERRED edges /graphify --update # incremental — re-extract only changed files /graphify --directed # preserve edge direction (source → target) /graphify --no-viz # skip HTML, just report + JSON /graphify --svg # also export graph.svg /graphify --graphml # export graph.graphml (Gephi, yEd) /graphify --neo4j # generate Cypher for Neo4j /graphify --obsidian # write Obsidian vault /graphify --wiki # build agent-crawlable wiki /graphify query "" # BFS traversal — broad context /graphify query "" --dfs # DFS — trace a specific path /graphify path "ModuleA" "ModuleB" # shortest path between two concepts /graphify explain "SomeNode" # plain-language explanation of a node /graphify add # fetch URL, add to corpus, update graph ``` ## Pipeline overview ### Fast path — existing graph Before running anything, check whether `graphify-out/graph.json` exists. If it does and the user's request is a natural-language question about the codebase (not an explicit rebuild command), skip straight to: ```bash graphify query "" ``` ### Step 1 — Install graphify ```bash # Preferred: uv tool install uv tool install --upgrade graphifyy # Fallback: pip pip install graphifyy ``` Save the Python interpreter path for subsequent steps: ```bash python -c "import sys; open('graphify-out/.graphify_python','w').write(sys.executable)" ``` ### Step 2 — Detect files ```bash python -c " import json from graphify.detect import detect from pathlib import Path result = detect(Path('')) print(json.dumps(result, ensure_ascii=False)) " > graphify-out/.graphify_detect.json ``` Present a clean summary (omit categories with 0 files): ``` Corpus: X files · ~Y words code: N files (.py .ts .go ...) docs: N files (.md .txt ...) papers: N files (.pdf ...) images: N files video: N files ``` If `total_files == 0`: stop with "No supported files found in [path]." If `total_files > 500` or `total_words > 2,000,000`: warn and offer to narrow to a subfolder before continuing. ### Step 3 — Extract entities and relationships Two parts run in parallel: **Part A — Structural (AST) extraction** for code files: ```bash python -c " from graphify.extract import collect_files, extract from pathlib import Path import json # ... load code files from detect output, run extract(), write graphify-out/.graphify_ast.json " ``` **Part B — Semantic extraction** for docs/papers/images: Dispatch parallel subagents (one per chunk of ~20-25 files). Each subagent reads its files, extracts entities and relationships, and writes a chunk JSON. After all chunks complete, merge them into `graphify-out/.graphify_semantic.json`. Check the extraction cache first — files already extracted can be skipped. **Part C — Merge** AST + semantic into `graphify-out/.graphify_extract.json`. ### Step 4 — Build graph, cluster, analyze ```bash python -c " from graphify.build import build_from_json from graphify.cluster import cluster, score_all from graphify.analyze import god_nodes, surprising_connections, suggest_questions from graphify.report import generate from graphify.export import to_json # ... build G, cluster, analyze, write GRAPH_REPORT.md and graph.json " ``` If the graph is empty after this step, stop and report — extraction produced no nodes. ### Step 5 — Label communities Read `.graphify_analysis.json`, assign 2-5 word plain-language names to each community (e.g. "Attention Mechanism", "Training Pipeline", "Data Loading"), then regenerate the report with the real labels. ### Step 6 — Generate outputs Always generate HTML (unless `--no-viz`): ```bash graphify export html ``` Obsidian vault only if `--obsidian` was explicitly given: ```bash graphify export obsidian [--dir ~/vaults/my-project] ``` Other exports (`--svg`, `--graphml`, `--neo4j`) only on their flags. ### Step 9 — Save manifest, clean up, report ``` Graph complete. Outputs in /graphify-out/ graph.html — interactive graph, open in browser GRAPH_REPORT.md — audit report graph.json — raw graph data ``` Then paste from the report into chat: - God Nodes - Surprising Connections - Suggested Questions Pick the single most interesting suggested question and offer to trace it. ## Confidence levels on edges Every edge carries a confidence tag: | Level | Meaning | |-------|---------| | `EXTRACTED` | Directly stated in the source (e.g., an import, an explicit reference). | | `INFERRED` | Reasonably implied by context (e.g., a function calls a module). | | `AMBIGUOUS` | Possible relationship but uncertain — treat as a lead, not a fact. | Never invent an edge. If unsure, use AMBIGUOUS. ## Community detection Graphify uses Louvain community detection (via NetworkX or graspologic) to group nodes into thematic clusters. Each community gets a human-readable label in Step 5. Communities surface cross-file connections that wouldn't be obvious from reading files individually. ## Incremental updates (`--update`) Re-extract only new or changed files; reuse cached results for unchanged files. Faster than a full rebuild for large corpora with minor changes. ## Query mode After a graph exists: ```bash graphify query "How does authentication flow through the system?" graphify query "What calls the database layer?" --dfs graphify path "AuthModule" "Database" graphify explain "UserService" ``` If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains; quote `source_location` when citing a specific fact. ## Troubleshooting **PowerShell vertical scrolling breaks after running graphify:** Caused by ANSI escape sequences from `graspologic`. Fix: upgrade graphify (`pip install --upgrade graphifyy`) or uninstall graspologic and let graphify fall back to NetworkX's built-in Louvain. **Graph is empty after extraction:** All files may have been skipped (binary-only corpus, encoding issues, or extraction subagents were dispatched as read-only). Re-run with `subagent_type="general-purpose"` so agents can write chunk files to disk. ## Guardrails - **Ambiguity stop:** if you cannot resolve the target path, STOP and ask — do not run the pipeline on an unintended folder. - **Retry cap:** any step that fails twice with the same error → stop and report verbatim. Never loop pip installs or re-dispatch failed chunks. - **Never delete `graphify-out/`** to "fix" an error. - **Never fabricate** nodes, edges, or answers not present in graph output. - **Done means:** the artifact exists on disk (e.g. `graphify-out/graph.json`, `GRAPH_REPORT.md`) — check with `ls`, don't assume. ## Honesty rules - Never invent an edge. If unsure, use AMBIGUOUS. - Always show token cost in the report. - Never hide cohesion scores — show raw numbers. - Never run HTML viz on a graph with more than 5,000 nodes without warning.