Graphify Hook

[! You only need this if you are creating an app with a large codebase, like tens of thousands of lines of code. You’ll want it when you see your AI consuming tens or hundreds of thousands of tokens just reading your codebase before it starts working.]

Even if you put this line in your CLAUDE.md file, Claude might skip it

`/graphify`: when the user types it, invoke the graphify skill before anything else. When you need to understand a codebase, read the knowledge graph first.

Why it happens: the graphify rule lives in your project CLAUDE.md as a should, not a must. When a prompt looks simple (“add X feature”), Claude often reaches for familiar tools (grep/Read/Explore agent) before it “remembers” to check for graphify-out/ first — especially after context compaction, when the CLAUDE.md instruction is further back in the conversation.

Options to force it:

1. UserPromptSubmit hook — fires on every prompt you send, before Claude sees it. It can inject a reminder or even prepend graphify query output automatically. Most reliable, since it runs outside Claude’s discretion entirely.
2. PreToolUse hook on Read/Grep/Glob — blocks or warns the first time Claude tries to read source directly, telling it to run graphify query first. More surgical, but can get annoying if it fires on legitimate small reads.

The Graphify skill documents the exact commands (graphify query, graphify path, graphify explain), and the skill itself has a “fast path” rule: if graphify-out/graph.json exists and the request is a natural-language question about the codebase, skip straight to running graphify query — no rebuild, no size checks.

That fast-path logic is exactly what a UserPromptSubmit hook should enforce mechanically, since it’s currently just a should-follow instruction Claude sometimes skips.

Recommended hook script logic (runs before every prompt reaches Claude):

#!/bin/bash
# .claude/hooks/graphify-check.sh
if [ -f "graphify-out/graph.json" ]; then
  cat <<'EOF'
This project has a knowledge graph at graphify-out/graph.json. Before using Grep, Read on
unfamiliar files, or the Explore agent, run `graphify query "<question>"` first (use
`graphify path "A" "B"` for relationships, `graphify explain "concept"` for a focused node).
Only fall back to raw file search if the graph query doesn't answer the question.
EOF
fi

The injected prompt text itself, if you want just the string for the hook config:

This project has a knowledge graph at graphify-out/graph.json. Before using Grep, Read on unfamiliar files, or the Explore agent, run graphify query "<question>" first (use graphify path "A" "B" for relationships, graphify explain "concept" for a focused node). Only fall back to raw file search if the graph query doesn’t answer the question.

A few notes on why this design:

• It only fires when graphify-out/graph.json actually exists (matches the skill’s own fast-path gate) — so it won’t misfire on projects without a graph.
• It’s phrased as a hard “before X, do Y” instruction, which hooks are good at reinforcing since they inject fresh into every turn, unlike CLAUDE.md which can get buried after compaction.
• I didn’t add a PreToolUse block on Grep/Read yet — that’s a stronger, more annoying enforcement (would need an allowlist for tiny reads). Worth adding only if the reminder alone doesn’t stick.

Summary of what I put in place, two complementary layers:

1. PreToolUse on Bash (pre-existing) — catches shell grep/rg/find commands and injects a graphify reminder.
2. UserPromptSubmit (new, .claude/settings.json + .claude/hooks/graphify-check.sh) — fires on every prompt you submit, injecting the reminder before Claude picks any tool (Grep, Read, or the Explore agent — none of which route through Bash, so layer 1 couldn’t catch them).

This is committed to the project’s tracked .claude/settings.json, so it applies to every session in this project. You can ask Claude to copy it to other projects.