Claude doesn't use graphify at all

[xuanswe]

I setup everything with claude hooks, github hooks, global claude.md and repo claude.md (using setup commands told in the repo and docs sites). Verify that graphify worked correctly by asking claude code to verify it. I run graphify for the whole repo.

But in real scenarios, claude code never uses graphify at all. I asked claude after the session, and it answered.

❯ in the whole session, did you and sub-agent use graphify at all?

No — neither I nor any subagent explicitly invoked graphify during this session. The graphify post-commit hook fired automatically on every commit (you can see it in the commit outputs: [graphify hook] launching background rebuild and [graphify doc-flag] markdown changed — wrote graphify-out/needs_update), but those are the hook running in the background, not deliberate invocations.

No graphify query, graphify path, graphify explain, or graphify update . were called. The implementation tasks were all in known files (the wireframes framework source), so no codebase exploration via graphify was needed.

The graphify-out/needs_update flag was written by those hook runs — if you want the doc-semantic layer refreshed you can run /graphify --update.

✻ Worked for 13s

❯ Why didn't you use it? I thought that we have instructions to force use it instead of some other tools?

Honest answer: the instructions were technically conditional, and most of this session fell outside their trigger — but there was one real gap.

The CLAUDE.md rule is "For codebase questions, first run graphify query…". Breaking down where that applied:

1. The controller (me): This session was executing an already-written 02-plan.md. Every task named the exact files, types, and code shapes to produce — there were no open codebase questions for me to answer; I dispatched tasks and committed results. So query/path/explain never had a trigger at my level.
2. graphify update . after modifying code: This obligation was satisfied automatically — the post-commit hook fired on every one of the 10 commits ([graphify hook] launching background rebuild in each commit output), and CLAUDE.md itself says the hook maintains the code/markdown structure layer for free. Running it manually would have been redundant.
3. The real gap — subagents. The implementer and reviewer subagents did exploratory Read/Grep inside the worktree to orient themselves (e.g., understanding CanvasNoteCard before refactoring it). I did not forward the graphify-first rule into their prompts, so none of them considered graphify query for those lookups. Two things softened the impact — they worked in a worktree where the graph reflected branch-point state, and I gave them full task text so their exploration was narrow — but strictly, that's where the instruction should have applied and didn't.

I'll save this as feedback so future sessions forward the graphify rule into subagent prompts:

  Recalled 1 memory, wrote 2 memories

Memory saved. To summarize the answer to your question:

Why graphify wasn't used this session:

1. Me (controller): I had no codebase questions to answer — the session executed a fully-specified 02-plan.md where every task named exact files and code shapes. The graphify rule triggers on "codebase questions," and plan execution didn't surface any at my level.
2. graphify update . after code changes: covered automatically — the post-commit hook fired on all 10 commits and maintains the code/markdown structure layer, per CLAUDE.md's own note.
3. The genuine miss — subagents: implementer and reviewer subagents did exploratory Read/Grep to orient in the code (e.g., understanding CanvasNoteCard before refactoring), and I didn't forward the graphify-first rule into their prompts, so they defaulted to grep/read. Subagents don't inherit session context — the rule only reaches them if the controller writes it into their task prompt.

I also see now (from the hook context that just fired) that you have a PreToolUse:Read hook injecting the graphify reminder — that reaches subagents' Read calls too, but it's advisory context they can ignore, not a block.

What I've changed: saved a feedback memory (forward-graphify-rule-to-subagents) so future sessions explicitly include "for codebase questions, first run graphify query" in every subagent prompt that involves code exploration, with the caveat that a fresh worktree's graph may be absent or stale.

Even after claude code saves to memory, next time, I still don't see it uses graphify. It continues to grep as usual.

[xuanswe]

I need to remove this for now because tokens are burning just for agents building graphify-out every commits and not using it.

[safishamsi]

Fixed in HEAD. Two changes:

1. CLAUDE.md template now uses MANDATORY language — changed from the conditional 'For codebase questions, first run...' to an explicit block:

MANDATORY: Before using Read, Grep, Glob, or Bash to explore the codebase, you MUST run graphify first.

It also now explicitly says: 'This applies to YOU and to every subagent you spawn. Include this rule explicitly in every subagent prompt that involves code exploration.'

2. PreToolUse hook message hardened — changed from advisory ('For codebase questions, run graphify query instead of reading files') to imperative ('MANDATORY: graphify-out/graph.json exists. You MUST run graphify before reading source files').

The root cause was that 'For codebase questions' was too narrow a trigger — Claude skips it when executing a plan where files are already named. The new wording removes the conditional and covers subagents explicitly.

Will ship in the next release. If you re-run graphify hook install and graphify setup after upgrading, the new CLAUDE.md block and hook message will apply.