Connect Graphify to Your Codebase in Easy 5 Steps (No API Key)

If you want to connect Graphify to your codebase, the good news is that you can do the entire setup — installation, the first graph build, and automatic rebuilds on every commit — without ever touching an API key, and without a single dollar leaving your wallet. I ran this exact setup on a private .NET project (a homelab monitoring dashboard called Stashboard), and this post walks through every command, every file it touches, and every limitation you hit when you skip the paid LLM step entirely.

What Graphify Actually Does

Graphify turns a folder of code (plus optionally docs, PDFs, and images) into a queryable knowledge graph instead of a flat vector index. It parses your code with tree-sitter — a real AST parser, not an LLM — and builds nodes and edges tagged either EXTRACTED (explicit relationships found in the code itself) or INFERRED (relationships an LLM guessed at). It supports 36 languages, ships as a CLI, and installs as a skill for 20+ AI coding assistants including Claude Code, Cursor, and GitHub Copilot — the same family of tools I’ve written about running self-hosted, like OpenClaw on a home server.

The pitch is simple: instead of your AI assistant grepping through hundreds of files to answer “how does scheduling work in this codebase,” it runs a graph query and gets back a scoped answer in a couple hundred tokens. That’s the mechanism working behind the scenes any time you connect Graphify to your codebase — and none of it requires an LLM for the code itself.

Prerequisites

Before you connect Graphify to your codebase, make sure you have:

Python 3.10 or newer
uv (recommended) or pipx/pip
An existing git repository you want to map
Optionally, Claude Code, Cursor, or another supported AI assistant, if you want the skill integration

Notice what’s not on this list: no API key, no signup, no billing account. That’s the whole point of the free code-only path.

Step 1 — Install the CLI

uv tool install graphifyy

This pulls down the CLI plus all the tree-sitter grammars it needs (C, C#, Go, Java, JavaScript, Python, Rust, and dozens more). On my machine this installed 30 packages in under a second and gave me two executables: graphify and graphify-mcp. Installing the CLI is the easy part of how you connect Graphify to your codebase — the real decisions come in the next two steps.

Step 2 — Register the Skill for Your AI Assistant

graphify claude install

This is the step most guides gloss over when they explain how to connect Graphify to your codebase, so pay attention here.

⚠️ Critical moment: this command does more than copy a skill file. On my repo it wrote a new section directly into CLAUDE.md (a file tracked in git) explaining to Claude Code when to query the graph instead of grepping. It also registered PreToolUse hooks in .claude/settings.json that run graphify hook-guard before every Bash, Read, and Glob call your AI assistant makes, in every future session in that repo. Before you run this, know that it’s a persistent, repo-wide behavior change, not a one-off action — check the diff with git diff CLAUDE.md .claude/settings.json afterward so you know exactly what it added.

In practice, hook-guard is a no-op until a graph actually exists. Once you build one, it nudges the assistant toward graphify query instead of brute-force file reads.

Step 3 — Connect Graphify to Your Codebase Without an API Token

This is where most people trip up when they try to connect Graphify to your codebase for the first time. If you naively run:

graphify .

…and your repo has any Markdown docs, PDFs, or images, it fails immediately:

error: no LLM API key found (135 doc/paper/image file(s) need semantic extraction).
Set GEMINI_API_KEY or GOOGLE_API_KEY (gemini), MOONSHOT_API_KEY (kimi),
ANTHROPIC_API_KEY (claude), OPENAI_API_KEY (openai), DEEPSEEK_API_KEY (deepseek),
or pass --backend. A code-only corpus needs no key.

The fix is the command Graphify itself recommends for staying free: run update instead of the bare path command.

graphify update .

This does AST-only extraction — no LLM call, no API key, no charge, ever. On my Stashboard repo (1,138 source files across src/ and tests/) it finished in under a minute and produced 11,618 nodes, 29,196 edges, and 731 communities, using 28 parallel workers automatically sized to my CPU. This is the command you’ll run any time you want to connect Graphify to your codebase’s current state without paying for anything.

Step 4 — Query the Graph

graphify query "how does monitor scheduling work"

Instead of a wall of grep hits, you get a scoped BFS traversal: 119 relevant nodes, starting from MonitorType and Stashboard.Core.Scheduling, surfacing exactly the classes and tests involved (CheckScheduleEvaluator, IMonitor, MonitorTests) — capped at a 2,000-token budget by default. Other useful commands: graphify explain "ConceptName" for a plain-language neighbor summary, and graphify path "A" "B" for the shortest relationship path between two symbols. This is the payoff of the whole exercise: once you connect Graphify to your codebase, every one of these queries stays free too — they’re just reads over the local graph.json file.

Step 5 — Install the Git Hooks

The last piece of how you connect Graphify to your codebase is automation: keeping the graph current every time you commit or switch branches, without remembering to run update by hand:

graphify hook install

This drops two shell scripts: .git/hooks/post-commit and .git/hooks/post-checkout. Here’s what’s actually happening inside them, because it’s more careful than a naive “run graphify on every commit” script:

They pin PYTHONHASHSEED=0. Community detection uses networkx’s Louvain algorithm, which iterates hash-ordered sets — without a pinned seed, community IDs would shuffle on every rebuild even with identical input.
They skip mid-operation. Both hooks bail out immediately if rebase-merge, rebase-apply, MERGE_HEAD, or CHERRY_PICK_HEAD exist in .git/, so they never interfere with a git rebase --continue.
They run detached, in the background. A full rebuild can take a long time on a huge repo, so the hook launches the rebuild as a detached subprocess and returns control to git commit immediately — your terminal doesn’t hang. Output goes to ~/.cache/graphify-rebuild.log.
They have a built-in timeout. By default a rebuild is capped at 600 seconds via GRAPHIFY_REBUILD_TIMEOUT, with a SIGALRM-based watchdog.
post-commit only rebuilds changed files, using git diff --name-only HEAD~1 HEAD, and skips entirely if the only changes are inside graphify-out/ itself (avoiding an infinite rebuild loop if you commit the graph output).
post-checkout only fires on real branch switches (the hook checks the third argument git passes, BRANCH_SWITCH=1), not on single-file restores like git checkout -- file.txt. When it fires, it re-extracts the checked-out tree, relying on Graphify’s content-hash cache so files identical to a previously-scanned version rebuild instantly.
There’s an escape hatch. Set GRAPHIFY_SKIP_HOOK=1 before a commit to skip the rebuild entirely, or run graphify hook uninstall to remove both hooks.

Once installed, every git commit triggers a background message like [graphify hook] launching background rebuild (log: ~/.cache/graphify-rebuild.log) and returns instantly, while the graph catches up a few seconds later. This is what makes it worth the effort to connect Graphify to your codebase properly instead of running update by hand — the graph just stays in sync on its own.

⚠️ One thing to know: git reset --hard is not a checkout, so it won’t trigger post-checkout. If you jump between commits that way, run graphify update . manually afterward.

Verifying It Works

After installing hooks, make a small commit and confirm the hook fired:

git commit -am "test commit"
cat ~/.cache/graphify-rebuild.log

You should see a line like [graphify hook] N file(s) changed - rebuilding graph... followed by a successful rebuild summary. Then re-run a query to confirm the graph reflects your latest change. If you see that, you’ve successfully managed to connect Graphify to your codebase end to end, from install to self-updating graph.

Limitations When You Connect Graphify to Your Codebase Without an API Key

This is the section most tutorials skip, so here’s the honest list of what you give up when you connect Graphify to your codebase and stay key-free:

No semantic reasoning about docs, PDFs, or images. Anything that isn’t source code (READMEs, design docs, screenshots, PDFs) is simply skipped — or blocks the whole run if you try the plain graphify . command instead of update. Your only free path for these is a local Ollama backend, which needs no API key but does need you to run a local model.
Only EXTRACTED edges, no INFERRED ones. Without an LLM pass, Graphify can only record relationships explicitly visible in the AST (calls, inheritance, imports). It won’t infer conceptual relationships that require actual reading comprehension.
Some files produce zero graph nodes. On my run, 132 files — mostly JSON configs like appsettings.json and settings.json — produced no nodes at all, since there’s no meaningful AST structure to extract from flat config files.
Community names stay generic. Without a backend, clusters are labeled Community N placeholders instead of human-readable names; the label command that renames them needs an LLM key.
No HTML visualization above ~5,000 nodes. My 11,618-node graph skipped graph.html generation automatically, with a suggestion to pass --no-viz or raise GRAPHIFY_VIZ_NODE_LIMIT if I wanted it anyway.

If you’re weighing whether to connect Graphify to your codebase this way, none of these limitations affect the core use case — letting your AI assistant navigate a large codebase efficiently — they only matter if you also want Graphify to reason about your prose documentation.

Should You Commit the Graph to Git?

Once you connect Graphify to your codebase, a natural question comes up: should the resulting graph live in git? For a solo project, no. graphify-out/graph.json regenerates in under a minute for free, and committing it just adds noisy diffs on every commit (11,618 nodes churns a lot of JSON). Add graphify-out/ to your .gitignore and let the hooks regenerate it locally. The one exception: if you ever pay for a semantic LLM pass over your docs and share the repo with a team, committing the graph preserves those expensive INFERRED edges for everyone else — that’s also why a merge-graphs command exists, for combining graph.json files across branches or repos.

Troubleshooting

Most of the problems people hit when they connect Graphify to your codebase trace back to one of five things:

“no LLM API key found” when you didn’t ask for semantic extraction — you ran graphify . instead of graphify update .. The bare path command always tries semantic extraction if it finds non-code files; update never does.
error: Executables already exist: graphify-mcp.exe, graphify.exe (use --force to overwrite) on uv tool install graphifyy — a previous install (or a different version) left stale executables behind, and uv refuses to clobber them silently. Re-run with uv tool install graphifyy --force.
uv trampoline failed to canonicalize script path right after that — this is the fallout from the error above: the package files got installed, but the .exe stubs (trampolines) are still pointing at the stale install and don’t match. It goes away once you re-run the install with --force, which rewrites both stubs cleanly.
Hooks don’t seem to fire — confirm graphify is on your PATH, or check graphify-out/.graphify_python, which the hook falls back to for locating the right interpreter.
Commit feels slow — it shouldn’t; rebuilds are detached. If it’s blocking, check whether antivirus scanning is delaying the Python subprocess spawn on Windows.

That’s the whole path to connect Graphify to your codebase for free: install with uv, build with update, wire it up with hook install, and query with graphify query. No API key, no subscription, no surprise invoice — just a graph that keeps itself in sync with your code.prise invoice — just a graph that keeps itself in sync with your code.

Connect Graphify to Your Codebase in 5 Steps (No API Key)