docs: add Graphify tool guide#18
Open
oto-macenauer-absa wants to merge 2 commits into
Open
Conversation
Add docs/tools/graphify.md: a guide to Graphify, the open-source skill that builds a local, queryable knowledge graph of a codebase so agents retrieve targeted context instead of re-reading files. Covers what it does, the Tree-sitter -> Leiden -> LLM-label pipeline, an honest token-savings assessment (reported ~7x-71x, biggest on large repos, build is not free), trade-offs (staleness, rebuild cost, Windows --update fragility), install/usage, and a suggested workflow. Web- researched and cross-checked; reviewed for accuracy and balance. Add Graphify to the docs and tools index tables.
oto-macenauer-absa
added
the
documentation
oto-macenauer-absa
requested review from
lsulak,
miroslavpojer and
tmikula-dev
as code owners
Elaborate on cost: the tool is free/open-source with no tiers; the only spend is LLM usage during the build, BYOK. Code parsing is local and free (Tree-sitter); the LLM is used only for semantic labels and non-code assets, and only derived descriptions leave the machine. Keep it provider-agnostic: cost is whatever you already pay your model provider, independent of the coding agent (Copilot CLI, Codex, Cursor, Claude Code). Backend table covers local (free) vs hosted (per-token); note the one-time amortised build cost and the code-only API-key gotcha (issue #1122). Tighten the related privacy and build-cost bullets.
|
|
||
| Because it's BYOK, your spend is **whatever you already pay your model provider** — independent of which coding agent you drive it from (GitHub Copilot CLI, Codex, Cursor, Claude Code, …). If your agent exposes its own model session, Graphify can reuse that without a separate key. | ||
|
|
||
| The build cost is **one-time and upfront**, proportional to how much code and (especially) non-code content you index, then amortised across every later query. As a rough scale, one indexed project reported a ~1.5M-token one-time build that paid back at ~46× average query reduction; large repos reach ~70×. |
Contributor
There was a problem hiding this comment.
How about maintenance costs?
The article does not mention they app can be changing by development.
| - **Staleness.** The graph is a snapshot at build time. After substantial code changes, an agent will read a stale graph and answer confidently from a map that is weeks out of date. Rebuild or `--update` after meaningful changes. | ||
| - **Rebuild cost.** Full rebuilds are CPU-heavy; without guards, concurrent rebuilds can pile up and saturate the machine. Incremental `--update` re-extracts only files whose content hash changed — but it carries the Windows caveat below. | ||
| - **`--update` is fragile on Windows** (cp1252 encoding, bash-quoting, graph-merge instability). On Windows, prefer a **full rebuild every few sessions** over per-session incremental updates. | ||
| - **Best as an audit, not a per-turn habit.** Several reviewers find it most valuable as a one-time architectural-understanding pass rather than something refreshed every session. |
Contributor
There was a problem hiding this comment.
I guess this could be valid usage for us, but what is the goal of audit?
- Find not used files?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
docs/tools/graphify.md— a guide to Graphify, the open-source skill that turns a codebase into a local, queryable knowledge graph so AI agents retrieve targeted context instead of re-grepping and re-reading files from scratch. Added to the docs and tools index tables.Contents
GRAPH_REPORT.md, and an optional HTML viz the agent reads before grepping.--updatefragility on Windows; best treated as a one-time architectural audit rather than a per-turn habit.pipx install graphifyy,graphify install,graphify .with--update/--mode deep/--no-viz;/graphifyin Claude Code. Suggested workflow included.Process notes
Based on
master(where the tools section lives).Closes #19