🗺️ Run Graphify and read the graph
You already have the source ready. Now run the command, wait for extraction, and learn how to read the results — the interactive map, the report with the hubs and questions, and the commands for talking to the graph directly in the terminal.
▶️ Run /graphify or graphify extract
There are two paths to generate the same graph. Inside Claude Code, you use the skill (the slash command /graphify; in a plain terminal, you use the subcommand headless graphify extract. Both read the source and produce the folder graphify-out/ — choose what fits the moment.
🔰 New here? Skill vs. headless
Skill = the way it works inside Claude Code: the session provides the model, so doesn't need an API key, and you get extras like --obsidian, --update e --watch. Headless = the same engine in a plain terminal (CI, script); for documents, it requires ANTHROPIC_API_KEY.
🎯 Objective: extract the graph from your documents folder without needing an API key.
/graphify ./claude-code-docs
Replace <isto-voce-troca>: ./claude-code-docs → the path to YOUR source prepared in module 2.2.
✓ How to verify: when it finishes, the folder appears graphify-out/ with graph.json, graph.html e GRAPH_REPORT.md.
🎯 Objective: the same extraction outside Claude Code (useful in CI or in a script).
graphify extract ./claude-code-docs
In headless mode, documents require ANTHROPIC_API_KEY in the environment. Pure code (tree-sitter) doesn’t need it.
✓ How to verify: same result as the skill—the folder graphify-out/ is created in the directory.
🔑 Key concepts
⏳ What happens during extraction
That progress bar isn't just sitting there for nothing. While you wait, Graphify reads the files and extracts entities (the nodes) and relationships (the typed edges), and then groups everything into communities using the algorithm Leiden. Each processed file goes into a cache, so the next run doesn’t redo what hasn’t changed.
🔰 New here? Leiden and cache
Leiden is the algorithm that finds groups of nodes that are highly connected to one another — the communities, the graph’s “neighborhoods.” The cache stores the result per file (by content hash); if the file hasn't changed, Graphify reuses it and doesn't call the model again.
↑ Waiting is real work: files → entities → relationships → communities. The cache underneath is what makes the 2nd round cheap.
🔑 Key concepts
🖥️ Open graph.html
Everything in the folder graphify-out/ derives from a single file: the graph.json, the source of truth. From it come the graph.html and the report GRAPH_REPORT.md. O graph.html é self-contained: opens directly in the browser, without starting any server.
↑ You run graphify about the corpus; it writes graph.json; and from it derive the graph.html (visual) and the GRAPH_REPORT.md (text).
🎯 Objective: see the actual graph — nodes, connections, and communities, interactive.
# macOS open graphify-out/graph.html # Linux xdg-open graphify-out/graph.html
✓ How to verify: opens a page with the web of nodes; drag, zoom, and click a node — all without a server.
📦 What's inside graphify-out/
| File | What it is |
|---|---|
| graph.json | Complete graph — the source of truth; everything else derives from it. |
| graph.html | Self-contained interactive visualization; opens in the browser, no server needed. |
| GRAPH_REPORT.md | Text audit: god nodes, connections between communities, and suggested questions. |
| cache/ | File-based cache (content hash) to avoid needlessly calling the LLM again. |
🔑 Key concepts
📋 Read GRAPH_REPORT.md
O GRAPH_REPORT.md is your entry point into a large graph. Instead of guessing where to explore, it gives you the god nodes — the most connected entities, the hubs—and a list of suggested questions that the graph can answer well. It’s an index of what the map knows.
🔰 New here? "God node"
A god node is the entity with the most connections in the graph — the hub. If a concept is linked to dozens of others, it's probably central to the project. Starting there is often the shortest path to understanding the whole.
# Graph Report ## God nodes (mais conectados) 1. Context Window — 38 conexões 2. Hooks — 31 conexões 3. Subagents — 27 conexões ## Perguntas sugeridas - Como funcionam os hooks? - O que liga Subagents a Context Window? - Quais comunidades giram em torno de MCP?
🎯 Objective: see god nodes and suggested questions in plain text.
cat graphify-out/GRAPH_REPORT.md
✓ How to verify: the section appears God nodes with a connection count and the list of Suggested questions.
🔑 Key concepts
🔎 explain / path / query in the terminal
Without opening the browser or the vault, you can talk to the graph directly in the terminal. explain describes a node in plain language; path shows the shortest path between two nodes; query answers an open-ended question. These answers come from the structure — fast and inexpensive.
🎯 Objective: explain a concept, find the connection between two, and ask an open-ended question.
graphify explain "Context Window" graphify path "Hooks" "Subagents" graphify query "como funcionam os hooks?"
Replace <isto-voce-troca>: the terms in quotes used by the nodes in YOUR graph (see the god nodes in the report).
✓ How to verify: each command responds in text—an explanation, a sequence of nodes along the path, or an answer to the question.
explain
Describes a node in plain language.
path
Shortest path between two nodes.
query
Ask the graph a free-form question.
🔑 Key concepts
🔁 --update and --watch (rerun cheaply)
The source changes over time—and you don't want to pay for the full extraction again. The --update reprocesses only the changed files (thanks to the cache); the --watch does this automatically every time you save. That’s what keeps the graph alive without incurring the full cost each time.
🎯 Objective: rerun only what changed — headlessly or inside Claude Code.
# headless: só os arquivos alterados graphify update ./claude-code-docs # dentro do Claude Code /graphify ./claude-code-docs --update /graphify ./claude-code-docs --watch
✓ How to verify: the run finishes much faster than the 1st extraction — the cache reuses what hasn’t changed.
✓ Incremental (--update / --watch)
- ✓Reprocesses only what changed.
- ✓Reuses the cache for each file.
- ✓Keeps the graph alive alongside the source.
✗ Extract from scratch every time
- ✗Calls the LLM again on the entire corpus.
- ✗It takes time and costs the full amount again.
- ✗Discourages keeping the graph up to date.
🔑 Key concepts
✋ Self-recovery (optional, non-blocking): which graphify-out/ lists the god nodes and suggested questions?
📌 Module summary
/graphify (skill, no key) and graphify extract (headless).Next module
2.4 · Generate the Obsidian vault — turn the graph into one Markdown file per concept, with wikilinks and backlinks.