How to Generate a Queryable Knowledge Graph for Any Codebase in 10 Minutes

Last week, I was pulled in to review an order service that hadn't seen major updates in three years. Over a hundred thousand lines of Java code, dozens of modules, and a README written six months ago. When a colleague asked me, "What services does the user checkout flow actually pass through?", I was stuck. Either I spent hours grep-ping, or I guessed the call chain by manually reading imports. It was incredibly inefficient.

If you've ever faced a similar situation—taking over an unfamiliar project, debugging cross-module bugs, or just wondering "where does this function actually call the database?"—this tutorial is for you.

I'll walk you through how to use Graphify to transform any project directory into an interactive knowledge graph. Then, we'll use natural language to ask questions and trace call paths. The whole process takes about 10 minutes. No need to read through every source file or study architecture diagrams upfront. Once it's running, you'll have instant clarity.

Prerequisites

Before we begin, make sure your environment meets these requirements:

• Python 3.10+ (Code parsing runs entirely locally with zero external API calls)
• Recommended: Use uv (Astral's modern Python package manager) or pipx. Both install the CLI into an isolated virtual environment, keeping your global Python setup clean.

Verify your setup:

python --version    # Requires ≥ 3.10
uv --version        # Optional, installation instructions below if missing

Why recommend uv/pipx over plain pip?

The Graphify CLI command is graphify, but the PyPI package is named graphifyy (notice the double y). Installing with standard pip often leaves the CLI out of your system PATH, leaving beginners stuck at command not found. uv and pipx handle environment isolation and PATH configuration automatically, minimizing friction.

Step 1: Install Graphify

Open your terminal and run these two commands:

## Install the CLI (recommended for isolated environment)
uv tool install graphifyy

## Register the skill with your AI editor (e.g., Claude Code, Cursor, etc.)
graphify install

After running graphify install, it will automatically write the skill configuration file based on your editor platform (Claude Code, Cursor, GitHub Copilot, etc.). No manual setup required.

Note: If you get a graphify: command not found error, run uv tool update-shell, restart your terminal, and try again. This is the most common issue on fresh macOS + zsh setups.

Step 2: Build a Graph for Your Project

Navigate to the root directory of the project you want to analyze. In your terminal or AI editor, simply type:

/graphify .

That's it. Graphify will use tree-sitter to locally parse the Abstract Syntax Trees (AST) of your code. The entire process relies on zero LLMs, requires no API keys, and keeps your code strictly on your machine. For supported languages (Python, Java, Go, Rust, TypeScript, and 30+ others), the parsing is fully deterministic.

Once finished, you'll find three files in the graphify-out/ directory:

graphify-out/
├── graph.html          # Open in any browser for interactive exploration: click nodes, filter communities, search
├── GRAPH_REPORT.md     # Executive summary: key concepts, unexpected connections, and recommended queries
└── graph.json          # Complete graph data for future queries without rescanning

Open graph.html in your browser. You'll see a force-directed graph where each node represents a code concept (classes, functions, interfaces, etc.). Edge colors denote different relationships, and distinct color blocks represent automatically clustered subsystems (communities). Click any node to expand its details.

Step 3: Query in Practice

Now that the graph is built, here's where the real productivity boost happens. You don't need to dig through files. Just ask.

I ran this on an open-source FastAPI project. Here are the actual outputs:

1. Explain a Node

graphify explain "APIRouter"

Output example:

Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

Connections (47):
  --> RequestValidationError [uses] [INFERRED]
  --> Dependant [uses] [INFERRED]
  --> .get() [method] [EXTRACTED]
  <-- __init__.py [imports] [EXTRACTED]
  ...

Every relationship edge carries a tag: EXTRACTED means it was explicitly found in the source code, while INFERRED indicates it was logically derived by Graphify during parsing. This transparency lets you know exactly what's hardcoded vs. what the tool deduced.

2. Trace Paths Between Two Concepts

This is probably my most-used command. For instance, to understand how FastAPI and ModelField are connected:

graphify path "FastAPI" "ModelField"

Output:

Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

A three-step call chain, instantly visible. This is incredibly useful when debugging or trying to grasp a framework's design.

3. Ask Natural Language Questions

graphify query "How does the auth module connect to the database?"

Instead of making you manually hunt through files, it returns a targeted subgraph answering your question.

Real-World Example: Analyzing a Spring Boot Order Service

Imagine you just cloned an order service repository and need to quickly grasp its architecture. Follow this workflow:

Step 6 is crucial — Graphify's graphs are designed for team sharing. Once committed, your teammates can pull and use them immediately without rebuilding. Combine this with graphify hook install (which automatically performs incremental updates on every git commit), and team collaboration becomes seamless.

Advanced Usage (Optional)

• Incremental updates only: /graphify . --update to skip full rebuilds
• Ignore directories: Create a .graphifyignore file (identical syntax to .gitignore to exclude node_modules/, dist/, etc.)
• Export to Obsidian: /graphify . --obsidian generates a Wiki-compatible structure for direct import into Obsidian
• PostgreSQL Integration: graphify extract --postgres "postgresql://user:pass@host/db" to map your database schema into the graph
• MCP Server: python -m graphify.serve graphify-out/graph.json exposes the graph via an MCP server for HTTP-based team access

Troubleshooting & FAQs

Q: I get graphify: command not found. What's wrong?
A: The PATH variable hasn't updated. Run uv tool update-shell or pipx ensurepath, then restart your terminal.

Q: Why does PyPI show a double y (graphifyy)?
A: The official package name indeed has two ys (graphifyy). The exposed CLI command is just graphify. Install with two ys, run with one. Don't mix them up.

Q: Can I use pip install instead?
A: Yes, but you'll likely run into PATH issues. Strongly recommend uv tool install graphifyy as your first choice.

Q: The graph is too large and crashes my browser.
A: Skip the HTML visualization and query the JSON directly: graphify query "..." --graph graphify-out/graph.json

Q: Do I need an API key?
A: No, not for code parsing. All code analysis runs locally via tree-sitter with zero API calls. LLMs are only used for semantic extraction of docs, PDFs, or images, and follow your AI editor's existing configuration.

Summary

Let's recap the workflow:

1. uv tool install graphifyy to install the CLI
2. graphify install to register with your editor
3. /graphify . to build the graph
4. graphify query/explain/path to explore
5. git add graphify-out/ to commit and share

This pipeline is perfect for quickly building a global understanding of a new codebase, debugging cross-module call chains, or creating onboarding materials for new hires. The 80k+ GitHub stars are well-deserved—it genuinely solves the daily pain of "digging through code until your head spins."

Next step: After installing Graphify, run it on your main project. Use graphify query to ask a few questions that normally require hours of source code reading. You'll immediately feel the difference in efficiency.