graphify

The Problem

Reading a large codebase means opening dozens of files, holding their structure in your head, and losing context between sessions. AI assistants like Claude Code and Codex are powerful, but they re-read raw files on every query, which is token-expensive and loses the forest for the trees. graphify solves this by building a persistent, queryable knowledge graph of a folder of code, docs, papers, or images, so an assistant can answer questions about a project without re-reading everything.

What This Does

graphify is an AI coding assistant skill. You invoke /graphify inside Claude Code, Codex, OpenCode, OpenClaw, or Factory Droid, and it processes the target folder into an interactive graph.html, a GRAPH_REPORT.md with god nodes and surprising connections, and a graph.json you can query weeks later. It supports 19 languages via tree-sitter AST parsing and uses Claude vision for multimodal inputs like PDFs and screenshots.

The core pipeline lives in graphify/ — extract.py does the heavy lifting (80 functions, 2,085 lines), build.py orchestrates, cluster.py runs Leiden community detection, and export.py generates the HTML/JSON output. The worked/ folder contains real-world example outputs (httpx, Karpathy repos, mixed corpora) that serve as reference artifacts.

How It Is Wired

Execution starts at graphify/__main__.py:302 (main), which reaches 20 functions. The install command (line 83) hooks the skill into your AI assistant. The serve entry point (graphify/serve.py:103) reaches 24 functions and starts the query server.

A run does this: main → _load_graph (reads filesystem) → extract.py's _make_id, _read_text, _resolve_name walk the target folder, building a NetworkX graph. The most-connected modules are graphify/build (10 importers), graphify/analyze (9), and graphify/cluster (8). The functions with the widest blast radius are _labels (called from 42 places), _make_graph (38), and _make_id (29) — changing any of these breaks a large swath of the codebase.

The walk function is the hottest path: it calls _make_id 41 times, add_edge 37, add_node 26, and _read_text 25. graphify/security.py makes outbound network calls (safe fetching), and graphify/detect.py handles file classification with cryptographic hashing. The module graph has zero circular dependencies, which keeps the pipeline acyclic and testable.

How To Use It

Setup: pip install graphifyy && graphify install (the PyPI package is temporarily named graphifyy). Requires Python 3.10+ and one of the supported AI assistants.

Running it:

/graphify .                        # works on any folder
graphify install --platform codex  # for Codex, opencode, or claw

Add a .graphifyignore file (same syntax as .gitignore) to exclude folders like vendor/ or node_modules/.

Configuration: No environment variables required. A pyproject.toml handles dependencies and build config.

Real-World Use

A team onboarding a new engineer runs /graphify on their monorepo. The new hire opens graph.html, sees the god nodes (the modules everyone imports), reads the GRAPH_REPORT.md for surprising connections, and queries graph.json for "what calls auth.py?" — all without a single LLM re-reading the raw source. The SHA256 cache means re-runs only process changed files.

Code Health & Issues

Static analysis (not opinion) found 25 findings: 4 high, 20 medium, 1 low.

• High — Deep nesting: graphify/extract.py, export.py, serve.py have max indentation depth of 11. Flatten with guard clauses.
• High — Oversized files: extract.py (2,085 lines) and export.py are too large to hold in one head. Split by responsibility.
• High — Duplicated code: 460 repeated 6-line blocks across 10 files including analyze.py, benchmark.py, serve.py. Extract shared helpers.
• Medium — Broad exception handling: 8 instances in cluster.py, extract.py, detect.py swallow errors indiscriminately.
• Medium — High branching density: 36 branch points over 89 lines in cluster.py, report.py, detect.py.

SDLC observations: no lockfile committed (non-reproducible builds), CI workflow lacks least-privilege GITHUB_TOKEN permissions, no Dependabot/Renovate, no dependency vulnerability scan, and no job timeouts. Tests are present (51 files) and CI runs on GitHub Actions.

The Bottom Line

graphify is a genuinely useful tool for AI-assisted codebase understanding, with a clean acyclic architecture and strong test coverage. The trade-off is that extract.py is a monolith that will be painful to modify, and the missing lockfile means your shipped artifact isn't bit-for-bit what you tested. Worth adopting if you live in an AI coding assistant and want persistent project context.