| name | graphify |
| description | Converts this codebase into a queryable knowledge graph so AI sessions query graph.json (71.5x fewer tokens) instead of reading raw source files. Integrates with Claude Code and Codex via repo hooks that auto-refresh on session start and after turns.
|
| triggers | ["/graphify","build knowledge graph","graphify the codebase","save tokens","reduce context","token optimization"] |
| references | ["CLAUDE.md","docs/architecture/overview.md",".claude/skills/repowise-intelligence/SKILL.md"] |
| upstream | https://github.com/safishamsi/graphify |
Skill: graphify — Knowledge Graph Token Optimization
Why This Exists
Reading raw source files to understand context is expensive. On a codebase this
size, a single "understand the auth flow" task can consume 8–20k tokens just in
file reads. Graphify pre-processes every file into a structured knowledge graph
(graph.json) using local AST parsing (no API calls for code). Claude queries
the graph instead of reading files — the upstream benchmark shows 71.5x fewer
tokens per query on large mixed corpora.
Installation (one-time per machine)
pip install graphifyy
graphify install
cd /path/to/local-llm-server
graphify .
On success you'll have:
graphify-out/graph.json ← local queryable graph (gitignored; path-specific IDs)
graphify-out/graph.html ← interactive visualization (gitignored, >5k nodes skipped)
graphify-out/GRAPH_REPORT.md ← god nodes, surprising edges, suggested questions
graphify-out/cache/ ← SHA256 change-detection cache (gitignored)
Session-Start Auto-Refresh
settings.json in this repo configures a SessionStart hook that runs
.claude/hooks/graphify-refresh --session when any Claude Code session opens. The wrapper runs graphify update . without unsupported flags, then prints the committed report summary. This keeps the graph current without full rebuilds — only changed files are re-processed.
The hook prints a one-line status so Claude knows the graph state:
=== GRAPHIFY KNOWLEDGE GRAPH (auto-loaded) === → report summary loaded; query graph.json[graphify] not installed → install with python -m pip install graphifyy and retry
How to Use the Graph (Token Savings Protocol)
Instead of reading raw files:
# EXPENSIVE (reads 300-line file = ~1200 tokens)
/graphify explain "How does ModelRouter select a model?"
# Returns a targeted 200-token answer from the pre-built graph
Key commands:
| Command | What it does |
|---|
graphify . | Full build with LLM semantic layer (needs API key) |
graphify update . | Incremental AST-only refresh — no API key needed |
graphify query "question" | Query conceptual relationships |
graphify path "ModelRouter" "proxy" | Find connection between two nodes |
graphify explain "Concept" | Detailed concept analysis from graph |
graphify watch . | Auto-sync as files change during development |
Claude's query protocol (use this instead of Read tool for exploration):
- Start session: Check
GRAPH_REPORT.md first — it lists god nodes (highest-connected
concepts) and surprising relationships for free.
- Targeted lookup:
graphify query "X" to understand a concept without opening files.
- Path tracing:
graphify path "A" "B" to trace how two modules connect.
- Only then open files: Use
Read only when you need the actual implementation
line numbers to make an edit.
Token Savings — Concrete Examples for This Repo
| Task (naive) | Tokens (raw read) | Tokens (graph query) | Saving |
|---|
| "How does auth work?" | ~6,000 (proxy.py + admin_auth.py + key_store.py) | ~200 | 30x |
| "What calls ModelRouter?" | ~4,000 (grep + read 3 files) | ~150 | 27x |
| "Agent loop dependencies" | ~8,000 (loop.py + tools.py + state.py) | ~300 | 27x |
| "All endpoints in proxy.py" | ~5,000 | ~180 | 28x |
Graph Artifacts — What to Commit
graphify-out/GRAPH_REPORT.md ✅ commit — portable readable summary (no machine-specific IDs)
graphify-out/graph.json ❌ gitignore — node IDs embed absolute checkout path; not portable
graphify-out/.graphify_labels.json ❌ gitignore — machine-specific
graphify-out/graph.html ❌ gitignore — skipped when >5k nodes anyway
graphify-out/cache/ ❌ gitignore — local SHA cache
graphify-out/.graphify_root ❌ gitignore — machine-specific absolute path
graphify-out/manifest.json ❌ gitignore — machine-specific absolute paths
graph.json is regenerated locally by the SessionStart hook (.claude/hooks/graphify-refresh --session) on every
session open — so each contributor gets a correct graph for their own checkout path.
Already configured in .gitignore for this repo.
Relationship to repowise-intelligence Skill
Both skills target token reduction through pre-computed codebase structure.
They are complementary:
- graphify: external tool, runs CLI, produces
graph.json + GRAPH_REPORT.md;
best for exploration queries and initial orientation.
- repowise-intelligence: internal skill, produces
.claude/skills/repowise-intelligence/intelligence/;
best for deep dependency tracing, git history, and decision archaeology.
Use graphify first (cheaper to bootstrap), escalate to repowise-intelligence
for questions graphify can't answer.
Acceptance Checks
