Tip: Graphify file writes invalidate prompt cache in Claude Code (Recommended docs update)

[Korck-lab]

Hello Graphify team!

Graphify is an awesome tool for providing structured context to AI coding agents. However, when run interactively inside Anthropic's Claude Code CLI, we detected a performance/cost gotcha that we wanted to share along with a recommended documentation update.

We developed claude-code-optimizer to audit local session logs for cache misses and token waste. Across 515 active projects utilizing Graphify (with 2,404 total command calls):

• The Issue: In 54 sessions, the Graphify tool generated output file writes (such as graph.json or graphify-out) in unignored workspace directories.
• The Cost Impact: Every time a file in the workspace is written to without being ignored, it instantly invalidates Claude's prompt cache. On the subsequent turn, Claude is forced to re-upload and re-parse the entire codebase context at full cache-write rates ($3.75/M tokens), losing the 90% caching discount.
• Recommended Mitigation: We suggest adding a tip in your README recommending that users add Graphify's output directories to their project's .claudignore file:

# .claudignore
graph.json
graphify-out/

This keeps the prompt cache warm and prevents costly invalidation loops when graphing the codebase!

[opnsrcntrbtr]

@safishamsi kindly confirm if below research of Graphify's inner architecture is valid in cotext of above issue and recommended mitigation:

How Claude Code Actually Accesses the Graph

Graphify installs a skill file into Claude Code — for example .claude/skills/graphify/SKILL.md — which is a set of instructions that teaches Claude Code how to invoke Graphify as a subprocess tool, not how to read graph.json directly as a file.

The skill file instructs Claude Code to prefer graphify query "..." and graphify path / explain commands over directly opening graph.json. When Claude runs graphify query "what connects auth to the database?", it's executing a shell command — the Graphify Python process reads graph.json internally, processes it, and returns a text answer back to Claude. .claudignore has no bearing on this at all.

What .claudignore Actually Controls
.claudignore tells Claude Code's file watcher and context injection system which files to exclude from automatic context loading and change tracking. It prevents Claude from:

Auto-reading a file and stuffing it into the prompt

Watching the file for changes and flagging it as "recently modified"

Including it in search/glob operations unless explicitly asked

It does not prevent:

Shell commands Claude issues from reading those files

MCP servers from reading those files

The Graphify CLI subprocess from reading those files

The Real-World Behaviour
So the proposed .claudignore fix works correctly in practice:

Claude Code won't auto-ingest graph.json (which could be huge — potentially hundreds of thousands of tokens) into the prompt on every turn ✅

Claude Code won't invalidate the cache when Graphify rewrites graph.json after a run ✅

Claude Code can still use graphify query "..." and the MCP server to query the graph on demand ✅

What the skill actually says about GRAPH_REPORT.md

The skill has a "fast path" rule that fires before anything else:

"If graphify-out/graph.json exists AND the user's request is a natural-language question about the codebase… skip Steps 1–5 entirely and jump straight to graphify query. Run graphify query "" immediately."

Then, at the very end of a build, the skill is instructed to paste only three sections from GRAPH_REPORT.md — God Nodes, Surprising Connections, and Suggested Questions — directly into the chat, not read the file passively. The report itself is described as an "audit report" output for the user, not a context document for the agent.
A more precise and updated .claudeignore that preserves full functionality while protecting the cache would be:

The Better Nuanced Fix

# .claudeignore — protect prompt cache from large volatile Graphify artifacts
# Graphify — protect prompt cache from volatile output artifacts.
# Claude queries the graph via graphify query "..." (CLI subprocess)
# or the MCP server — it never needs to read these files directly.
graphify-out/

[sub4biz]

The nuanced breakdown is helpful. One question on keeping GRAPH_REPORT.md outside .claudignore: you describe it as "small and stable", but it gets rewritten on every cluster-only run (and every full rebuild), so it would still trigger cache invalidation periodically. Given that the graphify skill already routes architecture questions through graphify query on demand, what's the practical benefit of having the report auto-loaded into context — is there a use case where passive context from GRAPH_REPORT.md adds value that an explicit query wouldn't cover?

Also: the granular file list doesn't cover the dated backup folders that graphify creates (graphify-out/2026-06-19/ etc.) — those would still invalidate cache after each run. Would graphify-out/ + !graphify-out/GRAPH_REPORT.md be a cleaner recommendation if the passive-context argument holds?