graphify

# /graphify Turn any folder of files into a navigable knowledge graph with community detection, an honest audit trail, and three outputs: interactive HTML, GraphRAG-ready JSON, and a plain-language GRAPH_REPORT.md. ## Usage ``` /graphify # full pipeline on current directory (HTML viz; add --obsidian for a vault) /graphify <path> # full pipeline on specific path /graphify https://github.com/<owner>/<repo> # clone repo then run full pipeline on it /graphify https://github.com/<owner>/<repo> --branch <branch> # clone a specific branch /graphify <url1> <url2> ... # clone multiple repos, build each, merge into one cross-repo graph /graphify <path> --mode deep # thorough extraction, richer INFERRED edges /graphify <path> --update # incremental - re-extract only new/changed files /graphify <path> --directed # build directed graph (preserves edge direction: source→target) /graphify <path> --whisper-model medium # use a larger Whisper model for better transcription accuracy /graphify <path> --cluster-only # rerun clustering on existing graph /graphify <path> --no-viz # skip visualization, just report + JSON /graphify <path> --html # (HTML is generated by default - this flag is a no-op) /graphify <path> --svg # also export graph.svg (embeds in Notion, GitHub) /graphify <path> --graphml # export graph.graphml (Gephi, yEd) /graphify <path> --neo4j # generate graphify-out/cypher.txt for Neo4j /graphify <path> --neo4j-push bolt://localhost:7687 # push directly to Neo4j /graphify <path> --falkordb # generate graphify-out/cypher.txt for FalkorDB /graphify <path> --falkordb-push falkordb://localhost:6379 # push directly to FalkorDB /graphify <path> --mcp # start MCP stdio server for agent access /graphify <path> --watch # watch folder, auto-rebuild on code changes (no LLM needed) /graphify <path> --wiki # build agent-crawlable wiki (index.md + one article per community) /graphify <path> --obsidian --obsidian-dir ~/vaults/my-project # write vault to custom path (e.g. existing vault) /graphify add <url> # fetch URL, save to ./raw, update graph /graphify add <url> --author "Name" # tag who wrote it /graphify add <url> --contributor "Name" # tag who added it to the corpus /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 "AuthModule" "Database" # shortest path between two concepts /graphify explain "SwinTransformer" # plain-language explanation of a node ``` ## What graphify is for Drop any folder of code, docs, papers, images, or video into graphify and get 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. ## What You Must Do When Invoked If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return. **Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it. If no path was given, use `.` (current directory). Do not ask the user for a path. If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL - run Step 0 before anything else, then continue with the resolved local path. Follow these steps in order. Do not skip steps. ### Step 0 - GitHub repos and multi-path merge (only if a URL or several paths) Only when the path is one or more `https://github.com/...` URLs, or several local subfolders to merge. See `references/github-and-merge.md` for the clone, cross-repo merge, and monorepo flow, then continue with the resolved local path. A plain local path skips this step. ### Step 1 - Ensure graphify is installed ```powershell # Detect Python with graphify — uv/pipx-aware (fixes #831) New-Item -ItemType Directory -Force -Path graphify-out | Out-Null $GRAPHIFY_PYTHON = $null function Find-GraphifyPython { # 1. uv tool install — 'uv tool dir' is authoritative, respects UV_TOOL_DIR automatically if (Get-Command uv -ErrorAction SilentlyContinue) { $uvDir = (uv tool dir 2>$null).Trim() if ($uvDir) { $py = Join-Path $uvDir "graphifyy\Scripts\python.exe" if (Test-Path $py) { & $py -c "import graphify" 2>$null if ($LASTEXITCODE -eq 0) { return $py } } } } # 2. pipx install — 'pipx environment' respects PIPX_HOME automatically if (Get-Command pipx -ErrorAction SilentlyContinue) { $venvs = (pipx environment --value PIPX_LOCAL_VENVS 2>$null).Trim() if ($venvs) { $py = Join-Path $venvs "graphifyy\Scripts\python.exe" if (Test-Path $py) { & $py -c "import graphify" 2>$null if ($LASTEXITCODE -eq 0) { return $py } } } } # 3. Active venv / conda / pip-into-current-env $pyCmd = Get-Command python -ErrorAction SilentlyContinue if ($pyCmd) { & $pyCmd.Source -c "import graphify" 2>$null if ($LASTEXITCODE -eq 0) { return (& $pyCmd.Source -c "import sys; print(sys.executable)").Trim() } } return $null } # Try to find the right Python (uv → pipx → active env) $GRAPHIFY_PYTHON = Find-GraphifyPython # Not found — install then re-detect if (-not $GRAPHIFY_PYTHON) { if (Get-Command uv -ErrorAction SilentlyContinue) { uv tool install --upgrade graphifyy -q 2>&1 | Select-Object -Last 3 } else { pip install graphifyy -q 2>&1 | Select-Object -Last 3 } $GRAPHIFY_PYTHON = Find-GraphifyPython } # Save interpreter path — all subsequent steps read this. # `Out-File -Encoding utf8` always writes a BOM on Windows PowerShell 5.1 (utf8NoBOM # only exists from PowerShell 6), and that BOM rides into the saved path, so the hook # rebuild fails with WinError 123 (#3028). WriteAllText with an explicit BOM-less # encoding writes the bytes POSIX writes, and adds no trailing newline. $Utf8NoBom = New-Object System.Text.UTF8Encoding $false [System.IO.File]::WriteAllText((Join-Path $PWD 'graphify-out\.graphify_python'), [string]$GRAPHIFY_PYTHON, $Utf8NoBom) # Save scan root so `graphify update` (no args) knows where to look next time. # INPUT_PATH is captured through a single-quoted (literal) here-string, never # substituted directly into the command line: an unquoted bareword argument # substituted here would let a malicious path (a stray `;`, `|`, or `$(...)`) # execute as script code the moment this line runs. $InputPathRaw = @' INPUT_PATH '@ [System.IO.File]::WriteAllText((Join-Path $PWD 'graphify-out\.graphify_root'), (Resolve-Path $InputPathRaw.Trim()).Path, $Utf8NoBom) ``` If the import succeeds, print nothing and move straight to Step 2. **In every subsequent block, run Python through the saved interpreter — `& (Get-Content graphify-out\.graphify_python)` in place of a bare `python3` — so every step uses the interpreter that actually has graphify.** ### Step 2 - Detect files ```powershell @' import json from graphify.detect import detect from pathlib import Path result = detect(Path('INPUT_PATH')) # Write the sidecar from Python, not a shell redirect, so the same block renders # on PowerShell hosts without console-encoding drift (#2528). Path('graphify-out/.graphify_detect.json').write_text(json.dumps(result, ensure_ascii=False), encoding="utf-8") print(f'Detected {result["total_files"]} files') '@ | & (Get-Content graphify-out\.graphify_python) - ``` Replace INPUT_PATH with the actual path the user provided. Do NOT cat or print the JSON - read it silently and present a clean summary instead: ``` 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 (.mp4 .mp3 ...) ``` Omit any category with 0 files from the summary. Then act on it: - If `total_files` is 0: stop with "No supported files found in [path]." - If `skipped_sensitive` is non-empty: report the count and list the skipped file names, so a wrongly-flagged source or doc is visible and can be renamed or moved (#2106). - If `total_words` > 2,000,000 OR `total_files` > 500: show the warning. Then compute the top 5 first-level subdirectories by file count: - Read `scan_root` from the detect JSON (always an absolute path to the resolved INPUT_PATH). - Concatenate all file lists across all types (`code`, `document`, `paper`, `image`, `video`). - Filter out any path that starts with `scan_root + "/graphify-out/"` to exclude converted sidecars. - For each file, strip the `scan_root` prefix and take the first path component. Files directly in `scan_root` with no subdirectory count as `(root)`. - If all files are in `(root)` with no subdirectories, do not ask to narrow — no subfolders exist. Instead suggest `--no-cluster` to skip the expensive clustering step and proceed. - Otherwise rank by count, show the top 5 with file counts, then ask which subfolder to run on. Wait for the user's answer before proceeding. - Otherwise: proceed directly to Step 2.5 if video files were detected, or Step 3 if not. ### Step 2.5 - Video and audio (only if video files detected) Skip this step entirely if `detect` returned zero `video` files. When the corpus has video or audio, see `references/transcribe.md` to transcribe them to text first, then treat the transcripts as doc files in Step 3. ### Step 3 - Extract entities and relationships **Before starting:** note whether `--mode deep` was given. You must pass `DEEP_MODE=true` to every subagent in Step B2 if it was. Track this from the original invocation - do not lose it. This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens). > **graphify needs no API key. Never ask the user for one, and never block on one.** Code is extracted structurally (AST) with no LLM and no key at all — a code-only corpus (the common `/graphify .` on a repo) skips semantic extraction entirely, so it needs nothing here: go straight to Part A and skip Part B. Semantic extraction (only for docs, papers, and images) uses Gemini **only if** `GEMINI_API_KEY`/`GOOGLE_API_KEY` is already set; otherwise the host agent itself is the LLM. graphify does **not** read `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or any other provider key. If you catch yourself about to prompt for, wait on, or stop because of a missing API key, that is a misread of this skill — proceed without one. **Before semantic extraction:** check whether `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set. If neither is set, print this one-liner to the user: > Tip: set `GEMINI_API_KEY` or `GOOGLE_API_KEY` to use Gemini for semantic extraction (`pip install 'graphifyy[gemini]'`). Print it once, then continue — do not wait for the user to supply a key. If `GEMINI_API_KEY` or `GOOGLE_API_KEY` IS set, use `graphify.llm.extract_corpus_parallel(files, backend="gemini")` for semantic extraction instead of dispatching subagents. The default Gemini model is `gemini-3-flash-preview`; set `GRAPHIFY_GEMINI_MODEL` or pass `--model` in headless CLI flows to override it. > **No other API keys are read.** When `GEMINI_API_KEY`/`GOOGLE_API_KEY` are unset, semantic extraction falls to the host agent itself — the running session is the LLM. On a host that dispatches subagents (e.g. Claude Code), dispatch them as written in Part B. On a host that runs the CLI directly in a terminal and cannot dispatch subagents, do not stall: a code-only corpus has no semantic work, so write the empty semantic file (Part B "Fast path") and continue to Part C; for a corpus with docs/papers/images, either set a Gemini key or extract those inline yourself, but in no case prompt for `ANTHROPIC_API_KEY` — that prompt is a misread of this skill. **Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.** Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers. #### Part A - Structural extraction for code files For any code files detected, run AST extraction in parallel with Part B subagents: ```powershell @' import sys, json from graphify.extract import collect_files, extract from pathlib import Path import json code_files = [] detect = json.loads(Path('graphify-out/.graphify_detect.json').read_text(encoding="utf-8")) for f in detect.get('files', {}).get('code', []): code_files.extend(collect_files(Path(f)) if Path(f).is_dir() else [Path(f)]) if code_files: result = extract(code_files, cache_root=Path('INPUT_PATH')) Path('graphify-out/.graphify_ast.json').write_text(json.dumps(result, indent=2, ensure_ascii=False), encoding="utf-8") print(f'AST: {len(result["nodes"])} nodes, {len(result["edges"])} edges') else: Path('graphify-out/.graphify_ast.json').write_text(json.dumps({'nodes':[],'edges':[],'input_tokens':0,'output_tokens':0}, ensure_ascii=False), encoding="utf-8") print('No code files - skipping AST extraction') '@ | & (Get-Content graphify-out\.graphify_python) - ``` #### Part B - Semantic extraction (parallel subagents) **Fast path:** If detection found zero docs, papers, and images (code-only corpus), skip Part B entirely and go straight to Part C. AST handles code - there is nothing for semantic subagents to do. **First write an empty semantic file** so Part C's merge has its input (it reads `.graphify_semantic.json` unconditionally; without this a code-only run hits `FileNotFoundError`): ```powershell @' import json from pathlib import Path Path('graphify-out/.graphify_semantic.json').write_text(json.dumps({'nodes':[],'edges':[],'hyperedges':[],'input_tokens':0,'output_tokens':0}), encoding='utf-8') '@ | & (Get-Content graphify-out\.graphify_python) - ``` **MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.** Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `graphify-out/.graphify_detect.json` - Estimate agents needed: `ceil(uncached_non_code_files / 22)` (chunk size is 20-25) - Estimate time: ~45s per agent batch (they run in parallel, so total ≈ 45s × ceil(agents/parallel_limit)) - Print: "Semantic extraction: ~N files → X agents, estimated ~Ys" **Step B0 - Check extraction cache first** Before dispatching any subagents, check which files already have cached extraction results: SPEC_PATH below is the **absolute** path of the `references/extraction-spec.md` that ships beside this SKILL.md — the same file Step B2 loads and hands to every subagent. It is the extraction prompt, so cache entries are attributed to it: when a graphify upgrade changes the prompt, entries produced by the old one are re-extracted instead of replayed, and unchanged prompts keep their entries (#1939). Substitute the real path in both Step B0 and Step B3 — pass the same one to each, and do not drop the argument. ```powershell @' import json from graphify.cache import check_semantic_cache from pathlib import Path