Graphify

What It Does

Graphify (published as the graphifyy PyPI package, v0.9.17) is a knowledge-graph skill for AI coding agents. You point it at a folder of code, docs, PDFs, images, or video, and it builds a traversable graph where every node is a symbol or concept and every edge is a relationship (calls, imports, contains, references) tagged with a confidence level. The output is three files in graphify-out/: an interactive graph.html you click through in a browser, a GRAPH_REPORT.md with the detected hubs and surprising connections, and a graph.json you query later without re-reading the source. The hook for agents is the query layer: instead of grepping, you run graphify explain "APIRouter" or graphify path "FastAPI" "ModelField" and get back a traced route through the graph.

The skill installs as a native SKILL.md into 23 coding agents (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenClaw, Hermes, Aider, Kilo, Kiro, OpenCode, Trae, Factory Droid, Devin, Amp, CodeBuddy, and others), and ships a separate graphify-mcp MCP server that exposes 10 graph-query and PR-impact tools. It targets developers working in large codebases who want an agent to answer "how does X work" by reading a graph rather than re-tokenizing the whole tree. It is built by Graphify Labs (a Y Combinator S26 company), has 89,706 stars, 8,754 forks, and 152 contributors, and was created on 2026-04-03.

The Good

The graph engine is deterministic, local, and verified end to end. The headline claim is that code is parsed with tree-sitter AST with no LLM and nothing leaving your machine. This is real. I built a graph on a 2-file Python project with graphify . --code-only and got 14 nodes, 15 edges, and 4 communities, with a token cost of zero and no API key set. The extraction pulls in 34 tree-sitter language grammars as hard dependencies (Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia, Verilog, Fortran, Bash, and more) plus 29 custom extractors in graphify/extractors/ covering languages tree-sitter handles poorly (SQL, Terraform, Apex, Dart, Blade, Razor, Pascal, DM). The source is 50,667 lines of Python across graphify/, with extract.py alone at 228 KB.

The Hermes skill install is first-class and correct. graphify install --platform hermes writes a 38 KB SKILL.md (valid frontmatter with name: graphify and a trigger description), a .graphify_version stamp, and a references/ directory with 8 progressive-disclosure sidecar files (add-watch, exports, extraction-spec, github-and-merge, hooks, query, transcribe, update) into ~/.hermes/skills/graphify/. The install code in graphify/install.py handles all three Hermes paths: project .hermes/skills/, global ~/.hermes/skills/, and Windows %LOCALAPPDATA%\hermes\skills (issue #1403). OpenClaw gets its own claw platform target. This is the correct, spec-compliant Hermes skill layout, not a copy into a generic directory.

The audit trail is honest and load-bearing. Every edge is tagged EXTRACTED (read directly from the source), INFERRED (resolved by graphify), or AMBIGUOUS. The graph_stats output for my test corpus reported "EXTRACTED: 100%, INFERRED: 0%, AMBIGUOUS: 0%", and the explain command annotated each connection with its tag and context ([calls] [EXTRACTED context=call]). For a tool that lets an agent reason over a codebase, knowing which edges are facts and which are guesses is the difference between trustworthy answers and confident hallucination.

The test suite is large and mostly green. uv run pytest produced 3341 passed, 16 failed, 33 skipped in 46 seconds across 148 test files. The test corpus is 50,222 lines, nearly a 1:1 ratio with the 50,667 lines of source. The 16 failures are all environment-specific: 14 live in test_skillgen.py and fail because they invoke git show against history that does not exist in my --depth 1 clone (the error is fatal: path 'graphify/skill-amp.md' exists on disk, but not in '47042be'), one needs an LLM backend for batch community naming, and the ollama retry tests need the ollama SDK installed. None are code defects.

The MCP server works and includes a novel PR-impact tool set. The graphify-mcp binary exposes 10 tools over the 2024-11-05 protocol: seven graph-query tools (query_graph, get_node, get_neighbors, get_community, god_nodes, graph_stats, shortest_path) plus three PR-impact tools (list_prs, get_pr_impact, triage_prs) that map which graph communities a pull request touches and report its blast radius. Calling tools/call graph_stats returned the real corpus data ("Nodes: 16, Edges: 16, Communities: 5, EXTRACTED: 100%"). The PR-impact layer, which cross-references GitHub PR file changes against the knowledge-graph communities, is something I have not seen in any other agent-skill MCP server.

The security model is documented and specific. SECURITY.md lists each threat vector paired with the function that mitigates it: security.validate_url() blocks private and loopback IPs plus cloud metadata endpoints for SSRF, security.validate_graph_path() confines MCP paths to graphify-out/, security.sanitize_label() HTML-escapes node labels and caps them at 256 characters to block XSS and prompt-injection-via-label, and _read_files() in llm.py wraps every source file in a hash-stamped block with _neutralise_injection_sentinels() defanging chat-template tokens. os.walk is called with followlinks=False throughout detect.py. The policy is explicit that graphify makes no network calls during analysis and does not use shell=True.

The Bad

Python type-hint dependencies are not extracted as graph edges. This is the most consequential gap. My test corpus defined class AuthModule with def __init__(self, store: UserStore), establishing a dependency from AuthModule to UserStore through the type annotation. Running graphify path "AuthModule" "User" returned "No path found between 'AuthModule' and 'User'." The explain output for AuthModule listed four connections, none of which was the UserStore parameter. For a tool whose core value proposition is "trace the path between two things," a relationship declared in a type hint being invisible to the graph is a real hole, and it is the common case in typed Python, TypeScript, Go, and Java codebases. The INFERRED edge type exists precisely to resolve this kind of cross-file reference, so the infrastructure is there, but the resolver does not close type-hint edges for the languages I tested.

Three different version numbers across three surfaces. The PyPI package reports graphify 0.9.17 from graphify --version. The repository pyproject.toml and CHANGELOG show 0.9.18 (unreleased). The MCP server, in its initialize response, reports serverInfo.version: "1.28.1". A user who installs the published package, reads the GitHub repo, and connects via MCP sees three different version strings with no obvious mapping between them. The 1.28.1 number in particular (higher than the 0.9.x CLI) looks like a stale or inherited value in serve.py rather than a deliberate scheme.

The MCP server crashes on first run if installed without the [mcp] extra. The default uv tool install graphifyy ships the graphify-mcp binary, but running it produces ModuleNotFoundError: No module named 'mcp' followed by ImportError: mcp not installed. Run: pip install "graphifyy[mcp]". The error message is helpful once you hit it, but a user who follows the install instructions, sees graphify-mcp on their PATH, and tries to use it gets a traceback. The fix is one line (declare mcp as a default dependency, or print the install hint before the import attempt), and the pyproject.toml already documents the extra clearly. The HTTP transport is also gated behind a separate starlette floor (CVE-2026-48818, CVE-2026-54283, pinned at >=1.3.1).

The full multi-modal promise requires a paid API key. The README leads with "turn any folder of code, docs, PDFs, images, or videos into a queryable knowledge graph." The code path is free and local, but the moment a non-code file is in the corpus the build aborts with error: no LLM API key found ... Set GEMINI_API_KEY or GOOGLE_API_KEY (gemini), ANTHROPIC_API_KEY (claude), OPENAI_API_KEY (openai), DEEPSEEK_API_KEY (deepseek). You must pass --code-only to skip the non-code files, or configure a key. The README does mention this in the body ("Docs, PDFs, images and video use your assistant's model"), but the headline framing undersells how often you hit the gate. A default --code-only fallback with a warning, rather than a hard abort, would smooth the first-run experience.

522 open issues and a changelog full of correctness fixes. The repo has 522 open issues, which is a lot of open surface even for a 152-contributor project. The 0.9.17 and 0.9.18 CHANGELOG entries are a dense run of extraction and incremental-rebuild correctness fixes: incomplete extractions no longer force-write partial graphs (#1951), graph.json now writes atomically (#1952), truncated LLM chunks are no longer cached as complete (#1950), and watch no longer duplicates concept nodes on every rebuild (#1954). Each fix is well-scoped and well-explained, but the volume signals that the incremental-extraction and caching logic is still settling. Anyone relying on graphify update or watch on a fast-moving repo should pin a version and watch the changelog.

Smoke Test Results

Tested on macOS (host, aarch64) with Python 3.12.13. The CLI was installed via uv tool install graphifyy (the recommended path) and also reinstalled with the [mcp] extra for MCP verification. The test corpus was a 2-file Python project (a UserStore, an AuthModule that depends on it via a type hint, and a User model).

Run B - Sandbox with deps preinstalled

$ uv tool install graphifyy
Installed 2 executables: graphify, graphify-mcp
PASS

$ graphify --version
graphify 0.9.17
PASS

$ graphify install --platform hermes
 skill installed -> /Users/openclaw/.hermes/skills/graphify/SKILL.md
PASS (valid SKILL.md + .graphify_version + 8-file references/ dir)

$ ls ~/.hermes/skills/graphify/
.graphify_version SKILL.md references/
PASS

Pass rate: 4 of 4. Install, version, help, and Hermes skill registration all work on the first try.

Full sandbox log ->

Run C - Functional verification (does it do what it claims?)

$ graphify . --code-only
wrote graphify-out/graph.json: 14 nodes, 15 edges, 4 communities
PASS (deterministic AST build, no LLM, 0 token cost)

$ graphify explain "AuthModule"
Node: AuthModule Source: src/app.py L12 Community: 2 Degree: 4
 --> .login() [method] [EXTRACTED]
 <-- Handles login using a UserStore. [rationale_for] [EXTRACTED]
PASS (source location + EXTRACTED-tagged edges)

$ graphify query "how does login work"
EDGE .login() --calls [EXTRACTED context=call]--> .get()
EDGE .login() --calls [EXTRACTED context=call]--> make_token()
PASS (traces the call flow)

$ graphify path "AuthModule" "User"
No path found between 'AuthModule' and 'User'.
FAIL (the AuthModule(store: UserStore) type-hint edge was never extracted)

$ graphify cluster-only . --no-label
Done - 4 communities. GRAPH_REPORT.md, graph.json and graph.html updated.
PASS (21 KB graph.html + report showing 100% EXTRACTED, god nodes ranked)

$ graphify update .
[graphify watch] Rebuilt: 16 nodes, 16 edges, 5 communities
PASS (incremental rebuild picks up the file change)

$ {initialize + tools/call graph_stats} | graphify-mcp
Nodes: 16 Edges: 16 Communities: 5 EXTRACTED: 100%
PASS (MCP server exposes 10 tools and returns real graph data)

Functional pass rate: 6 of 7. The single failure is the path query on an unextracted type-hint edge.

Full functional log ->

What the runs tell you

The core graph-building and query engine does exactly what it claims for the local, code-only path: deterministic tree-sitter extraction, honest EXTRACTED/INFERRED tagging, working explain and query commands, a real HTML visualization, incremental updates, and a 10-tool MCP server. The one functional miss is a genuine extraction limitation (type-hint dependencies are not edges), not an install or runtime failure. Anyone evaluating graphify for a typed codebase should run graphify path on a few real cross-module relationships before relying on it for navigation.

Setup Walkthrough

1. Install the CLI with uv: uv tool install graphifyy. This adds graphify and graphify-mcp to ~/.local/bin and pulls the 34 tree-sitter grammars. Takes roughly 5 seconds.

1. Register the skill with your agent. For Hermes: graphify install --platform hermes. This writes ~/.hermes/skills/graphify/SKILL.md plus its references/ directory. Other platforms use the same --platform flag (claude, codex, cursor, gemini, claw, copilot, aider, kilo, kiro, opencode, trae, droid, devin, amp, agents, codebuddy, antigravity, windows, pi).

1. Build a graph on your project. From the project root, run graphify . for the full pipeline or graphify . --code-only to skip non-code files and avoid the API-key gate. Output lands in graphify-out/ (graph.html, GRAPH_REPORT.md, graph.json).

1. Query it. graphify explain "", graphify path "" "", and graphify query "" all read graphify-out/graph.json without re-extracting.