Give Your Coding Assistant a Map Instead of a Flashlight

We're spending too many AI tokens (and minutes of wall-clock time) every time our coding assistants re-read the same files trying to understand our codebase. Graphify (github.com/safishamsi/graphify) builds a one-time knowledge graph of our project — code, SQL schemas, docs, infrastructure — that Claude Code, Copilot, Cursor, Codex, and Gemini CLI can query instead of reading raw files. Less grepping, faster answers, lower token bills.

The problem we keep hitting

Every time someone asks their AI assistant "where does X connect to Y?" or "why does the auth flow touch the billing service?", here's what actually happens under the hood:

• The assistant runs grep, find, or repeated read_file calls.
• It pulls thousands of lines of source into the context window just to locate a few relevant ones.
• Half the tokens are spent on files that turn out to be irrelevant.
• For larger repos, it gives up or hallucinates after running out of context.

This is the dominant cost driver in our agent usage right now. It's also the slowest part of most coding sessions — we wait while the model reads things it already read yesterday.

What Graphify does

You run one command in the repo root:

/graphify .

It produces three artifacts:

• graph.html — an interactive visualisation you can open in a browser.
• GRAPH_REPORT.md — a human-readable map (god nodes, surprising connections, design rationale pulled from comments and docs).
• graph.json — the full queryable graph.

After that, the assistant reads the graph instead of the raw repo. Every relationship — function calls, schema references, import chains, doc-to-code links — is precomputed and confidence-tagged (EXTRACTED, INFERRED, or AMBIGUOUS).

It supports 25 languages plus SQL schemas, shell scripts, PDFs, Office docs, and even videos/papers — so our app code, DB schema, and infra docs end up in one graph.

Why this speeds up code pattern recognition

Two reasons:

1. Patterns are already extracted. Tree-sitter does AST-level extraction locally (no API call) for code. Cross-file references — "every service that calls RateLimiter", "every table that joins to users" — are nodes-and-edges in the graph, not something the model has to re-derive each session. Asking "show me everywhere we implement retry-with-backoff" becomes a graph lookup instead of a 30-file scan.
2. The "why" is captured. Inline # NOTE:, # WHY:, # HACK: comments and docstrings become separate nodes linked to the code they describe. The assistant sees the design rationale alongside the implementation, so it stops suggesting changes that we already considered and rejected six months ago.

Why this reduces token consumption

Three concrete savings:

• No more exploratory file reads. Hooks on Claude Code, Codex, and Gemini CLI fire before every read_file call and route the assistant through the graph first. The model only pulls the specific files the graph points to.
• Compact context. GRAPH_REPORT.md is a few KB. Stuffing that into context replaces tens of thousands of tokens worth of speculative file reads.
• Incremental rebuilds. --update re-extracts only changed files. A graphify hook install makes this run automatically on every git commit, so the graph stays fresh without anyone thinking about it.

In practice: a question that used to cost ~50K input tokens and 4–5 tool calls drops to a single graph query plus one or two targeted reads. That's the headline win.

How we'll roll it out

1. One of us runs /graphify . at the repo root and commits the graphify-out/ folder so everyone on the team starts with the same map. Add graphify-out/manifest.json and graphify-out/cost.json to .gitignore (the manifest is mtime-based and breaks after git clone; cost.json is local-only). Optionally also ignore graphify-out/cache/ to keep the repo small, or commit it for faster rebuilds.
2. Everyone pulls. From that point on, your assistant reads the graph automatically.
3. Run graphify hook install once locally so the graph rebuilds on every commit (AST extraction only — no API cost on rebuild).
4. Run the install command for whichever assistant you use:

graphify claude install    # Claude Code
graphify copilot install   # Copilot CLI
graphify cursor install    # Cursor
graphify codex install     # Codex
graphify gemini install    # Gemini CLI

Install Graphify itself with uv tool install graphifyy or pipx install graphifyy (note the double-y in the PyPI name).

What I'd like from you

Try it on one of your active branches this week and post a quick before/after in the thread — even rough numbers ("normally takes 3 minutes to find this, took 20 seconds"). If it lands the way I expect, we'll commit a graph to the main repo and make it the default workflow.

Repo: github.com/safishamsi/graphify

Docs worth skimming: the "How it works" page and the team setup section of the README.