How to Use Graphify with Cursor: Turn Your Codebase into a Queryable Knowledge Graph

Cursor is excellent at writing code, but it has one persistent weakness: context. When you ask it a question about a large codebase, it grep's, reads files, and burns through tokens trying to reconstruct what your project actually does. On anything bigger than a side project, that gets slow, expensive, and unreliable.

Graphify fixes this by turning your repo into a queryable knowledge graph that Cursor can consult directly — code, docs, PDFs, even YouTube transcripts, all linked by what calls what and what explains what. Instead of grepping, Cursor asks the graph.

We use Graphify on every project at Zolosoft— including the very Next.js site you're reading this on. This guide walks through the exact setup we use, from a clean Mac to a working /graphify command inside Cursor, and the handful of habits that make it actually pay off.

What is Graphify, exactly?

Graphify is an open-source skill that AI coding assistants can call. It does two things:

1. Extracts a knowledge graphfrom a folder of code, docs, papers, images, or videos. Code is parsed locally with tree-sitter (31 languages, no API calls). Everything else goes through your IDE's model API for semantic extraction.
2. Exposes that graph to your assistant via graphify query, graphify path, and graphify explain commands — plus an MCP server for tool-call access.

The output is three files in a graphify-out/ folder:

graph.html        # interactive browser visualization
GRAPH_REPORT.md   # god nodes, surprising connections, suggested questions
graph.json        # the full graph — query it anytime

The trick is that Cursor doesn't load all of these by default. Instead, Graphify installs a small Cursor rule that tells the agent: “before you grep, try graphify query "<question>". It'll give you a scoped subgraph that's much smaller than the full report.” That single nudge changes how Cursor answers questions about your project.

Why this matters for Cursor specifically

Cursor's agent mode is essentially a tool-using loop. Every unnecessary file read costs latency and tokens, and every wrong file read leads the agent down a dead end. Without a graph, Cursor has three options for understanding your code:

• Grep — fast but blind to relationships. Finds strings, not concepts.
• Read entire files — accurate but token-heavy. Burns your context window.
• Semantic search— better, but still file-level. It can't tell you that FunctionA in one file calls FunctionB in another via a third indirection.

Graphify gives Cursor a fourth option: ask the graph. The graph already knows that generateMetadata() calls getServiceBySlug(), that SERVICES is a god node touched by 6 other modules, and which functions are surprisingly connected across files. Cursor gets the answer in a few hundred tokens instead of a few thousand.

Prerequisites

You need Python 3.10 or newer and a package manager that puts CLIs on your PATH. We recommend uv:

python3 --version    # need 3.10+
uv --version         # any version is fine

If you don't have uv yet:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# macOS (Homebrew)
brew install uv

# Windows
winget install astral-sh.uv

Install Graphify and wire it into Cursor

Two commands. The first installs the CLI; the second registers it with Cursor.

uv tool install graphifyy   # note the double "y"

Verify the install:

graphify --version

Now register the skill with Cursor:

graphify cursor install

This does two things:

• Writes a .cursor/rules/graphify.mdcrule file in your project. This is the “always-on” instruction that tells Cursor to consult the graph before grepping.
• Makes the /graphify slash command available inside Cursor chat.

Restart Cursor (or reload the window) so it picks up the new rule.

Build your first graph

Open your project in Cursor, then type this into the chat:

/graphify .

Cursor will invoke Graphify on the current folder. On a Next.js project our size (~40 source files), it takes about 30 seconds. You can watch progress in the terminal panel. When it's done you'll see:

graphify-out/
├── graph.html         # open in a browser
├── GRAPH_REPORT.md    # the highlights
├── graph.json         # the full graph
├── manifest.json
└── cache/             # AST cache, makes updates instant

Open graph.htmlin a browser. Click nodes. Filter by community. This is your project's map — every function, type, config block, and doc heading, with the edges showing what calls or references what.

Skim GRAPH_REPORT.md — particularly the sections on God Nodes (your most-connected concepts) and Surprising Connections (relationships that span files or modules). The first time you read this report on a non-trivial codebase is genuinely a moment of clarity.

Querying the graph from Cursor

Once the graph exists, Cursor's agent will start preferring graph queries on its own — that's what the rule file is for. But you can also call them yourself when you want a targeted answer:

# scoped subgraph for a natural-language question
graphify query "what connects auth to the database?"

# shortest dependency path between two symbols
graphify path "UserService" "DatabasePool"

# expanded explanation of a single concept
graphify explain "RateLimiter"

In practice the queries we run most often look like this:

• graphify query "where do we validate user input?" — locates every validator across the codebase, including ones that live in middleware.
• graphify path "Navbar" "SERVICES" — answers “how does the nav end up showing services?” without you needing to remember the import chain.
• graphify explain "generateStaticParams" — pulls the function plus every page it's defined on, with inline doc comments attached.

The output is a scoped subgraph — usually 5–20 nodes — which Cursor feeds into its context window as compact, structured data. It's the difference between asking a senior engineer for a code tour and handing them a 200-page printout.

Keep the graph fresh automatically

A stale graph is worse than no graph because it confidently points to files that don't exist anymore. The fix is a one-liner:

graphify hook install

This installs two git hooks:

• post-commit — re-runs AST extraction after every commit. No API cost; takes a couple of seconds.
• post-checkout — refreshes the graph when you switch branches.

It also sets up a git merge driver for graph.json so two devs can commit in parallel and have their graphs union-merged automatically. No more conflict markers in generated files.

For docs and PDFs that need LLM extraction, run a manual update when the content changes:

graphify update ./docs

Setting it up for a team

Graphify is designed for graphify-out/ to be committed to git. That way the first person to set up the project bears the LLM cost, and everyone else clones a repo that already has a working map. Their Cursor reads the graph immediately.

Recommended .gitignore additions:

graphify-out/manifest.json    # mtime-based, breaks after git clone
graphify-out/cost.json        # local only
# graphify-out/cache/         # optional: skip to keep the repo smaller

And a .graphifyignore in your project root, same syntax as .gitignore, to exclude generated code, vendored deps, and anything else you don't want in the graph:

node_modules/
.next/
dist/
build/
*.generated.ts
public/legacy/

What we've learned using it in production

A few patterns that took us a couple of weeks to figure out and might save you the time:

Build before you ask

The biggest mistake is asking Cursor a hard architectural question before you've run /graphify . once. The rule file nudges Cursor toward the graph, but only if the graph actually exists. On a new repo, run it first; everything else flows from there.

Use queries instead of opening the report

It's tempting to read GRAPH_REPORT.md directly for everything. Don't — that's the same problem we were trying to solve. Use graphify query for specific questions; reserve the report for broad architecture review on day one.

Tune the resolution

If a community in the graph feels too large to be meaningful, rerun clustering with finer granularity:

graphify cluster-only . --resolution 1.5

Higher resolution → more, smaller communities. We default to 1.0 and bump to 1.5 on monorepos.

Exclude super-hubs from god-node rankings

Utility files that everything imports (think constants.ts, types.ts) can dominate the “god nodes” list and make it less interesting. Drop them:

graphify cluster-only . --exclude-hubs 99

Add external context the agent can't see

Graphify can ingest external resources as graph nodes — arxiv papers, YouTube videos, PDFs, anything you'd normally have open in another tab while debugging:

graphify add https://arxiv.org/abs/1706.03762
graphify add https://www.youtube.com/watch?v=<id>

Once added, they're queryable the same way as your code. Useful for embedding domain knowledge — a payments SDK's docs, a compliance PDF — directly into the graph your assistant consults.

Common pitfalls

graphify: command not found

Plain pip install graphifyydrops the script in a user bin that isn't always on your PATH. Switch to uv tool install graphifyy or pipx install graphifyy — both manage PATH automatically. As a fallback, python -m graphify works.

Graph has fewer nodes after an update

If a refactor deleted files, Graphify keeps the old graph as a safety check. Force the overwrite:

graphify update . --force
# or
GRAPHIFY_FORCE=1 graphify update .

Duplicate nodes for the same entity

Occasionally semantic and AST extraction disagree on a node ID and you end up with ghost duplicates. A full re-extract cleans it up:

graphify extract . --force

HTML viz is too heavy to open

On repos over ~5,000 nodes the visualization gets unwieldy. Skip the HTML and just use the JSON + queries:

graphify cluster-only . --no-viz

Where to go from here

Once Graphify is part of your daily workflow, two follow-ups are worth knowing:

• The MCP server. Run python -m graphify.serve graphify-out/graph.json to expose the graph as an MCP tool. Useful when you want repeated structured access — Cursor (and other clients) can call query_graph, shortest_path, and get_neighbors as proper tools.
• The PR dashboard. graphify prsuses the graph to rank open PRs by impact and flag merge-order risk (PRs touching the same graph community). On a team it's a quiet productivity bump.

Closing thoughts

Most “AI coding” advice is about prompts. Graphify is infrastructure. It changes what the assistant can know in the first place, which turns out to matter much more than how cleverly you phrase the question. Five minutes of setup, a git hook, and a single rule file is all it takes for Cursor to stop grepping and start navigating your codebase.

If you'd like help wiring Graphify (or a broader AI tooling story) into your own product, we do this for clients all the time. Have a look at our AI Solutions work, or book a free 30-minute call.