Graphify: Navigate Our Codebase by Structure, Not Similarity

How a knowledge graph replaces vector search, cuts retrieval to 71× fewer tokens, and gives our coding agent a structural map instead of keyword matches.

Every RAG system we’ve built over a codebase hits the same wall. We ask how module A connects to module B and get back chunks about each one separately, with nothing about the connection.

That’s not a prompting problem; That’s a similarity problem. Our embeddings match on words. Our dependency chains run on call graphs.

Two functions that call each other can have completely different vocabulary, and no amount of cosine similarity will surface that relationship.

Hit the paywall? No worries, read the full post here for free.

Graphify replaces similarity with structure. Instead of embedding our files into a vector store, it builds a knowledge graph from our codebase’s real architecture call graphs, imports, dependency chains and lets our coding agent navigate by structure instead of keyword matching.

pip install graphifyy && graphify install

Open any coding agent. Type /graphify . on any folder, That's it.

What We Get Back

After Graphify runs, it produces a graphify-out/ folder:

graphify-out/
├── graph.html       # Interactive visualization — click nodes, search, filter
├── GRAPH_REPORT.md  # God nodes, communities, surprising connections
├── graph.json       # Persistent graph — query weeks later without re-reading
└── cache/           # SHA256 cache — re-runs only process changed files

GRAPH_REPORT.md is what changes how our agent works.

It maps the most-connected nodes in our codebase (the "god nodes" everything routes through), which components cluster together and surprising cross-community connections that reveal hidden dependencies we didn't know existed.

We can query the graph directly from the terminal:

graphify query "what connects the auth flow to the payment handler?"
graphify path "DigestAuth" "Response"
graphify explain "SwinTransformer"

On Graphify’s own benchmark, a 52-file mixed corpus of Karpathy’s nanoGPT, minGPT and micrograd repos plus research papers and images, a query costs roughly 1,700 tokens against the graph versus 123,000 tokens reading the raw files.

That’s a 71.5× reduction, and the structured version actually contains the relationships that raw text buries in noise.

How It Builds the Graph

The architecture runs three extraction passes, each at a different cost.

Pass 1: AST extraction (free, no LLM)

This is the core of Graphify. Tree-sitter parses our code across 20 languages Python, TypeScript, Go, Rust, Java, C, C++, and thirteen others and extracts classes, functions, imports, call graphs, docstrings, and rationale comments.

Entirely local, entirely deterministic. For a pure code repository, this pass alone often produces a sufficient structural map, Zero API cost.

Pass 2: Local transcription (free, no LLM)

Video and audio files get transcribed locally with faster-whisper, using a domain-aware prompt derived from the graph’s most-connected nodes.

Transcripts are cached by SHA256, so re-runs skip already-processed files. YouTube links work too.

Pass 3: Claude subagents (costs API tokens)

For documents, papers, PDFs, images, screenshots and whiteboard photos, Claude subagents run in parallel to extract concepts, relationships, and design rationale.

This is the only pass that costs tokens and it’s where the graph becomes multimodal.

A whiteboard screenshot connects to the code that implements the architecture it describes, which connects to the paper that motivated the design.

All three passes merge into a single NetworkX graph. Leiden community detection then clusters nodes by edge density, grouping tightly connected components into communities.

Structure Instead of Similarity, How It Actually Works

This is the architectural bet at the heart of Graphify.

The semantic relationships that Claude extracts are already in the graph as edges, tagged INFERRED with confidence scores. They influence community detection directly through the graph structure.

Leiden finds communities by edge density, not by cosine similarity in embedding space.

The graph topology is the similarity signal. No separate embedding step, no vector database.

Every relationship is tagged so we know what was found versus what was guessed: EXTRACTED (found directly in source), INFERRED (reasonable inference with a confidence score), or AMBIGUOUS (flagged for our review).

How It Plugs into Our Agent

Graphify supports ten platforms: Claude Code, Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, Aider, OpenClaw, Factory Droid, and Trae.

On Claude Code, a PreToolUse hook fires before every Glob and Grep call. If a knowledge graph exists, our agent consults GRAPH_REPORT.md for structure before searching raw files navigating by architecture instead of grepping through everything.

Cursor uses .cursor/rules/graphify.mdc with alwaysApply: true. Codex and Gemini CLI have similar hooks.

Platforms without hook support fall back to AGENTS.md.

For agents that support tool calling, Graphify also runs as an MCP server, exposing query_graph, get_node, get_neighbors and shortest_path as structured tools.

Drop Anything, Graph Everything

Andrej Karpathy is known for keeping a /raw folder where he drops papers, tweets, screenshots and research notes, Graphify was built 48 hours after Karpathy posted his LLM Knowledge Bases workflow, and it's designed for exactly this pattern.

Drop anything into a folder, run one command, get a queryable knowledge graph connecting concepts across our code, docs, images and video.

A .graphifyignore file (same syntax as .gitignore) excludes what we don't want. Incremental updates (--update) re-extract only changed files.

Watch mode (--watch) auto-syncs as files change in real time.

Where Similarity Still Wins

Graphify and vector RAG answer different classes of questions.

If we need “find paragraphs similar to this one” or “what documentation mentions error handling”, vector search is still the right tool.

Graphify solves for structure: connections, dependencies, architectural decisions, design rationale.

Most production systems will eventually use both.

The cost structure splits cleanly. Passes 1 and 2 are free and local. Pass 3 costs API tokens, and for large documentation sets or image-heavy corpora, that cost is real.

On a pure code repo with minimal docs, the cost is near zero. And graph quality depends on corpus quality, if our codebase has no docstrings and no comments explaining intent, the graph will be thinner.

Early, Fast-Moving, Already Useful

Graphify is early and moving fast. The API surface is still evolving. Expect breaking changes between versions. But the tool is already genuinely useful for understanding unfamiliar codebases and navigating large projects treat it as an actively developing project, not a stable dependency.

Graphify is at github.com/safishamsi/graphify, MIT licensed. The PyPI package is graphifyy (note the double y).

The team is building Penpax on top of the graph layer: an on-device digital twin that connects meetings, browser history, files, emails, and code into one continuously updating knowledge graph with no cloud dependency.