Use Cases & Workflows

Practical scenarios and the CLI commands to handle them.

Core Use Cases

Onboarding to a New Codebase

Drop into a new project, run /graphify ., and immediately see which modules are the architectural pillars (god nodes), how the codebase clusters into logical areas (communities), and surprising connections you'd miss reading files linearly.

Research Paper + Code Integration

Working with academic papers alongside code (common in ML)? Graphify connects concepts across both. Paper concepts link to code implementations via semantically_similar_to edges. Query "what connects attention to the optimizer?" to traverse both paper and code nodes.

Architecture Documentation

The GRAPH_REPORT.md is an auto-generated architecture document that stays current with your code. With the always-on hook, your AI assistant reads this report before answering architecture questions.

Code Review Context

Before reviewing a PR, query the graph to understand the blast radius: which god nodes and communities are affected by the changed files.

Essential Commands

Quick Reference (click to copy)

# Build graph for current directory
/graphify .

# Build graph for a specific folder
/graphify ./src

# Query the graph
/graphify query "what connects auth to the database?"

# Trace a path between two nodes
/graphify path "UserService" "DatabasePool"

# Explain a specific concept
/graphify explain "CausalSelfAttention"

Workflows

First-Time Setup

Install Graphify

pip install graphifyy && graphify install

Build initial graph

/graphify . — reads all files, builds graph, exports to graphify-out/

Enable always-on hook

graphify claude install — writes CLAUDE.md section + PreToolUse hook

Install git hooks (optional)

graphify hook install — auto-rebuild on commit and branch switch

Daily Development

Code changes auto-tracked

Git hooks rebuild the graph after each commit (AST only, no LLM cost)

Ask architecture questions

The always-on hook means Claude reads GRAPH_REPORT.md before searching files

Deep queries when needed

/graphify query "..." traverses the raw graph for edge-level detail

Adding New Content

# Add a paper
/graphify add https://arxiv.org/abs/1706.03762

# Add a tweet
/graphify add https://x.com/karpathy/status/...

# Update graph with new files
/graphify . --update

Advanced Commands

Command	Purpose
`--mode deep`	More aggressive INFERRED edge extraction
`--update`	Only re-extract changed files, merge into existing graph
`--cluster-only`	Rerun clustering without re-extraction
`--no-viz`	Skip HTML, just produce report + JSON
`--watch`	Auto-sync graph as files change
`--wiki`	Build agent-crawlable wiki
`--obsidian`	Generate Obsidian vault
`--svg`	Export static SVG diagram
`--graphml`	Export for Gephi/yEd
`--neo4j`	Generate Cypher statements
`--neo4j-push bolt://...`	Push directly to Neo4j
`--mcp`	Start MCP stdio server

Token Efficiency

Token Reduction by Corpus Size

Corpus	Files	Naive Tokens	Graph Query	Reduction
Karpathy repos + papers + images	52	~123K	~1.7K	71.5x
graphify source + Transformer paper	4	~12K	~2.2K	5.4x
httpx (synthetic, 6 files)	6	~6K	~5K	~1x

Key insight: Token reduction scales with corpus size. Small projects (~6 files) fit in a context window anyway. At 52+ files, you get 71x+ savings. The first run costs tokens to build; every subsequent query saves them.

Known Limitations

Graph drift on incremental updates: Stale relationships from earlier runs can persist. Recommendation: full re-index after major structural changes.
Semantic extraction is probabilistic: Claude/GPT-4 extraction varies by model version. Confidence scores mitigate this but don't eliminate it.
Louvain fallback on sparse graphs: Can be slow without tuned parameters (fixed in v0.3.10).
PyPI name: Package is graphifyy (name graphify being reclaimed).

← Implementation Ecosystem →