Graphify on Safairbru — Setup Guide

Phase 1 Install ⏱ 2 min

STEP 1

Install Graphify

Python package + CLI

Graphify is a pip package. Requires Python 3.10+.

pip install graphifyy --break-system-packages

💡 Note the double y in graphifyy — that's the actual PyPI package name, not a typo.

Verify it installed:

graphify --help

STEP 2

Install as a Claude Code skill

Makes /graphify available in Claude Code sessions

This copies the skill file to ~/.claude/skills/graphify/SKILL.md so any Claude Code session can invoke /graphify.

graphify install

Alternatively, if you prefer manual install:

mkdir -p ~/.claude/skills/graphify
curl -fsSL https://raw.githubusercontent.com/safishamsi/graphify/v3/graphify/skill.md \
  > ~/.claude/skills/graphify/SKILL.md

⚠ You already have 80+ skills in ~/.claude/skills/. The graphify install command writes to that same location, so it'll fit right in. But check it doesn't overwrite anything — do an ls ~/.claude/skills/graphify/ first.

Phase 2 First Run on Safairbru ⏱ 5–15 min

STEP 3

Create a .graphifyignore

Exclude noise before scanning

Graphify respects a .graphifyignore file (same syntax as .gitignore). Create one in the Safairbru root to skip heavy directories that won't help understanding the code:

node_modules/
vendor/
dist/
build/
.git/
*.min.js
*.min.css
*.map
__pycache__/
*.pyc
.venv/
static/vendor/
*.generated.*

💡 Adapt this to Safairbru's actual structure. If it has a large static/ or migrations/ folder, consider excluding those too. The leaner the input, the cleaner the graph.

STEP 4

Run the extraction

Generate the knowledge graph

You have two options. Start with the default run (AST + LLM) to get the full picture, or use the Claude Code skill:

Option A: From the terminal (standalone)

cd ~/path/to/safairbru
graphify .

Option B: From inside Claude Code

/graphify .

⚠ The LLM pass costs tokens. It sends chunks of docs, PDFs, and images to Claude for concept extraction. For a first run, this is fine — you want the full graph. But see Step 9 for when to skip it on subsequent runs.

For a large codebase, this may take 5–15 minutes. The AST pass (code files) is fast and deterministic. The LLM pass (docs, images) runs in parallel subagents and is where the time goes.

What happens during extraction

Pass	What it extracts	Cost
AST (deterministic)	Classes, functions, imports, call graphs across 19 languages via tree-sitter	Free — no LLM calls
LLM (parallel subagents)	Concepts from docs, PDFs, images, markdown. Relationships tagged EXTRACTED / INFERRED / AMBIGUOUS	Token cost — proportional to doc volume

STEP 5

Review the output

Understand what Graphify produced

After extraction, you'll find a graphify-out/ directory in the project root:

graphify-out/
  graph.html          # Interactive visual graph — open in browser
  GRAPH_REPORT.md     # God nodes, key connections, suggested questions
  graph.json          # The knowledge graph — this is what Claude reads
  cache/              # SHA256 cache — re-runs only process changed files

What to look at first

1. Open graph.html in a browser. Click nodes, search, filter by community. This gives you a visual map of how Safairbru is structured — what connects to what, which modules are central ("god nodes"), and which are isolated.

2. Read GRAPH_REPORT.md. This is the summary Graphify writes for the AI. It identifies the most connected entities, surprising relationships, and suggests questions you can ask. This is what Claude will read before exploring files.

3. Spot-check graph.json. This is the raw graph data. You don't need to read it yourself, but it's worth checking the size — if it's huge (>5MB), you may want to tighten the .graphifyignore.

💡 The graph.html visualization is genuinely useful for the rewrite. It shows you which modules are tightly coupled (hard to change independently) vs loosely coupled (safe to rewrite in isolation). Start the rewrite with the loosely coupled modules.

Phase 3 Integrate with Claude Code ⏱ 5 min

STEP 6

Wire into CLAUDE.md

Tell Claude sessions to read the graph report

Add this section to Safairbru's CLAUDE.md:

## Code Knowledge Graph

A Graphify knowledge graph exists at `graphify-out/`. Before exploring code structure,
architecture questions, or "where does X connect to Y" queries:

1. Read `graphify-out/GRAPH_REPORT.md` for god nodes, community structure, key connections
2. Use `/graphify query "your question"` for graph-backed answers (cheaper than raw file reads)
3. After significant code changes, run `/graphify . --update` to refresh the graph

The graph covers: classes, functions, imports, call graphs, doc concepts, and relationships.
Each edge is tagged EXTRACTED (from code), INFERRED (model-reasoned), or AMBIGUOUS.

This ensures every Claude Code session that opens Safairbru knows the graph exists and reads the report before doing expensive file exploration.

STEP 7

Install the PreToolUse hook

Auto-surface the graph before file searches

This is the killer feature. A PreToolUse hook fires before every Glob/Grep call, nudging Claude to check the graph report first instead of brute-force searching files.

graphify claude install

This does two things:

Writes a section to CLAUDE.md (you may want to merge with what you added in Step 6)
Adds a PreToolUse hook to .claude/settings.json that fires before Glob and Grep calls

⚠ Check your existing settings.json first. If Safairbru already has Claude Code settings (permissions, hooks), the install command may overwrite them. Back up .claude/settings.json before running, then merge manually if needed.

The hook message Claude sees before each search:

graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes
and community structure before searching raw files.

To uninstall later: graphify claude uninstall

STEP 8

Test it works

Verify Claude uses the graph

Open a fresh Claude Code session in the Safairbru directory and ask an architecture question:

What are the main modules in this codebase and how do they connect?

Watch for Claude reading GRAPH_REPORT.md first (you should see the Read tool call). If it goes straight to Glob/Grep instead, the hook or CLAUDE.md wiring needs adjustment.

Also try a graph query directly:

/graphify query "what are the god nodes in this codebase?"

💡 Compare token usage. Ask the same architecture question in a session WITH the graph vs one WITHOUT (in a fresh directory without graphify-out). The token difference is where the "71.5x reduction" claim comes from. In practice, expect 5–20x depending on codebase size.

Phase 4 Decisions & Ongoing Use ⏱ 2 min

STEP 9

AST-only vs full LLM pass

When to use each mode

Graphify doesn't have a --no-llm flag (as of v3). But the AST and LLM passes work on different file types, so you control the scope via .graphifyignore:

Scenario	What to do	Why
First run	Full run: `graphify .`	You want the complete picture before the rewrite. Both code structure AND doc concepts.
After code changes	`graphify . --update`	Only re-extracts changed files (cache tracks SHA256). Fast and cheap.
Just recluster	`graphify . --cluster-only`	Recomputes communities on existing graph. No extraction, no tokens.
Code-only (skip docs)	Add `.md`, `.txt`, `.pdf`, `.png` to `.graphifyignore`, then run	AST pass runs on code files only (free). LLM pass has nothing to process. Effectively "AST-only."
Deep extraction	`graphify . --mode deep`	More aggressive INFERRED edge extraction. More tokens but finds more connections.

💡 Recommendation for the Safairbru rewrite: Do a full first run to map everything. Then use --update after each significant rewrite milestone. The cache means re-runs are cheap — only changed files get re-processed.

STEP 10

Keep the graph fresh during the rewrite

Options for ongoing sync

The graph is a snapshot. As you rewrite Safairbru, the graph gets stale. Here are your options:

Option A: Watch mode (auto-sync)

graphify . --watch

Monitors file changes and auto-updates the graph. Good for active development sessions. Runs in the background.

Option B: Git hook (update on commit)

graphify hook install

Auto-rebuilds the graph on every commit and branch switch. Good for "set and forget" — the graph is always current when you start a new session.

Option C: Manual update (cheapest)

graphify . --update

Run this when you want a fresh graph. The cache ensures only changed files get re-processed.

⚠ Community feedback (Reddit): Multiple users noted that keeping the graph fresh is the main maintenance burden. The git hook approach (Option B) has the best effort-to-freshness ratio. The --watch mode is newer and may have rough edges.

💡 For the rewrite specifically: Use Option C (manual). You're rewriting large chunks, so the graph will need significant regeneration anyway. Run --update at each milestone (e.g., "finished rewriting the auth module") rather than continuously. Once the rewrite settles, switch to git hooks.