jared
/
cc-os
1
0
Fork 0
Code Issues 17 Pull Requests Packages Projects Releases Wiki Activity
cc-os/docs/graphify/external-tips.md

16 KiB
Raw Blame History

Graphify: Community Tips & Independent Perspectives

Outside-the-docs notes on Graphify (PyPI package graphifyy, CLI graphify, by Safi Shamsi) — gathered from third-party reviews, GitHub issues, and primary data endpoints. This file deliberately favors independent and skeptical sources over the official marketing, and flags where the two disagree. See also 07-token-economics-and-updates.md and 02-installation-setup.md.

Source quality warning. Much of the "review" content circulating about Graphify (knightli, openclawapi, augmentcode, several Medium posts) reads like SEO/AI-generated echo: it repeats the official headline numbers without measuring anything. Five blogs quoting "58.3K stars" is one claim, not five corroborations. The only substantively independent skeptical source found is roborhythms, which actually tested. Treat everything else as restated marketing.

Community setup tips

  • Install graphifyy with the double-y. The PyPI package is graphifyy; the CLI it installs is graphify. Getting this wrong is called out as "the single most common installation mistake." community Confirmed by the official PyPI page.
  • uv tool install graphifyy is the recommended path, with pipx install graphifyy and pip install graphifyy as alternatives, followed by graphify install (or graphify claude install for Claude Code specifically). official
  • Backends are now opt-in extras. As of v0.8.30 the Claude/Anthropic backend installs via the [anthropic] extra; other extras include pdf, office, google, video, mcp, neo4j, svg, leiden, ollama, openai, gemini, bedrock, sql, dm, chinese, all. official Install only what you need rather than [all].
  • Commit the output for team sharing. Outputs land in a graphify-out/ directory (graph.html, GRAPH_REPORT.md, graph.json); checking these in lets teammates on any AI assistant share one graph. community
  • Don't trust every edge. Relationships are confidence-tagged EXTRACTED / INFERRED / AMBIGUOUS; reviewers recommend reading that metadata rather than treating the graph as ground truth. community

Known gotchas & workarounds (with links)

  • Some users measure more tokens, not fewer. In issue #580 a user reports that after graphify claude install, Claude Code prefaces answers with "Let me read the Graphify knowledge graph first as instructed," reads GRAPH_REPORT, and consistently uses more tokens than asking directly — across multiple queries in one session. Two other users (sumitparakh, spperforce) confirmed the same behavior in the thread. Status: the issue is closed, but no maintainer fix or explanation is visible in the thread — closure does not equal resolution here. community This is a direct, independently-corroborated contradiction of the token-savings pitch on small/medium codebases.
  • The agent can silently bypass the graph. Issue #1114 (closed, "help wanted"): the PreToolUse hook only intercepts Bash grep — it does not catch the Read tool, so the agent can just read files directly and ignore the graph entirely. roborhythms independently flags the PreToolUse hook as "silently broken on Claude Code v2.1.117 and later." community / community
  • Git hooks no-op on uv tool/pipx installs. Issue #1127 (closed): graphify hook install silently does nothing for isolated-environment installs because interpreter detection ignored .graphify_python. If your post-commit auto-rebuild "isn't firing," this is likely why — check you're on a version after this fix. community
  • Stale nodes accumulate. Issue #1116 (open): graphify update leaks stale nodes — symbols removed from files that still exist are never pruned, so the graph drifts from reality over time. community
  • Code-only repos still demand an LLM API key. Issue #1122 (open): extract requires an LLM API key even for code-only corpora, despite code extraction making no LLM calls. Annoying if you wanted pure local AST indexing. community
  • The architecture-overview tool is itself a token hog. roborhythms found the overview tool can return up to ~131,000 characters (~33,000 tokens) — a "hidden token trap" that can erase your savings on a single call. community
  • Graphs are build-time snapshots. They go stale and need manual rebuilds; this is the headline limitation everyone repeats. community
    • Workaround: keep graphify update in git hooks, never per-turn AI hooks — graphify update takes ~10s+ on a real monorepo and will "pile up, hang in the background, and saturate CPU/RAM" if wired to an AI turn hook. Use graphify hook install (installs post-commit + post-checkout, both backgrounded; post-checkout does incremental for ≤5 changed files, full rebuild otherwise). community
    • The same write-up reports real resource blowups — "3 stuck processes at 65–73% CPU each, load average 12+, RAM saturated" from rapid-fire commits — and adds CPU/RAM guards (_resources_ok(), pgrep guards, timeout 300) to its hook scripts. Worth borrowing if you commit frequently. community
  • Legacy Java produces noisy communities. roborhythms: "almost everything imports Logger," so god-node/community detection gets polluted on old Java codebases. community
  • God-node centrality has been inflated by extractor bugs. Issue #563 (closed) documented two extractor bugs that "systematically inflate god-node centrality" (rationale fragments + a calls-direction inversion). Fixed, but a reminder that god-node rankings have been wrong before. community

The token-savings debate (independent takes)

The "71x" headline is real but cherry-picked — this is the most important independent finding. roborhythms (Nathan Cole) tested across codebase sizes and explicitly debunks the viral number: "The 71x figure comes from a single specific benchmark… It is real, but it is the upper bound on a curve that includes much more modest savings for smaller tasks." His measured ranges: community

Codebase size Independently measured savings
Under 100 files 1x–3x (negligible — "naive grep is already cheap")
100–500 files 6x–15x
500–5,000 files 30x–49x
5,000+ files up to 71x (but with build-time problems)
  • Strongest corroboration: roborhythms reproduced a large-monorepo query at "about 123,000 tokens… Graphify answered in about 1,700" — i.e. the big-codebase savings are directionally real. A separate Medium author claims 71.5x on a 52-file corpus, but that number is implausible against roborhythms' "<100 files = ~1–3x" finding and should be treated as marketing, not data. community / community
  • Strongest skepticism: issue #580 — multiple users measuring a net increase in tokens on smaller projects, because the mandatory "read the graph first" preamble plus GRAPH_REPORT costs more than it saves. This squarely contradicts the official framing for small repos.
  • roborhythms' practical verdict: install if your monthly token bill exceeds ~$50 on a 100+ file codebase; skip small projects. community

Headline-stat verification (checked against primary endpoints, 2026-06-03):

Official/marketing claim Independently verified value Verdict
~43K stars (per task brief) 58,848 stars via GitHub API Brief is stale/low; real count is higher. official
500K downloads (per task brief) 1,283,025 total downloads via pepy.tech Brief is stale/low; real count is ~2.5x higher. community
70x–90x token savings 71x is a real upper bound, not typical Misleading as a headline; true for huge repos only. community

Note the context for the stats: the repo was created 2026-04-03 (GitHub API) — roughly two months before this writing — so 58K stars and 1.28M downloads represent genuinely explosive, viral growth, not a long tail. The numbers are large; whether the token-savings claims live up to the hype is the part that needs the asterisk.

Roadmap signals from issues/releases

Release cadence is extreme (~123 releases, often multiple per day; current 0.8.30, 2026-06-02). Themes from recent releases and open issues: official

  • Context-cost reduction is now an explicit goal. v0.8.29 shipped "progressive-disclosure skill files reducing context load by ~47%" (issue #1106), and v0.8.30 added a "Read-tool graph bypass nudge" — a direct response to the bypass problem in #1114. official
  • Security hardening. v0.8.29: local providers made opt-in, office/PDF screening, metadata-address blocking, file-bomb protections. official
  • Cross-language depth. v0.8.22–0.8.27 added type-reference and inheritance edges across Swift/Kotlin/PHP/Rust/Go/ObjC/Julia/C++/TypeScript; determinism fixes (stable community IDs). official
  • Open pain points to watch: stale-node pruning (#1116), API-key-for-code-only (#1122), hardcoded 600s claude-cli timeout (#1112), headless image ingestion reading images as garbage (#1109), and a requested direct-Postgres connection (#1093).

Alternatives people compare it to

  • code-review-graph (CRG): SQLite-backed AST graph with blast-radius analysis, embedding-based semantic search, ~25 MCP tools, and sub-second incremental updates — fast enough to run in a Claude Stop hook (unlike Graphify). One write-up runs the two together with a fallback chain "CRG semantic (miss) → graphify query → grep." community
  • Caveman: orthogonal, not a competitor — it compresses output ("~65% fewer output tokens") rather than input. Tip: pair them — Graphify on the input side, Caveman on the output side. Caveat from the same author: "Graphify won't untangle a genuinely messy codebase" and "Caveman won't fix bad answers — it just makes bad answers shorter." community
  • Understand-Anything (Lum1104): a Claude Code plugin with a multi-agent pipeline that builds a per-file/function/class knowledge graph plus an interactive dashboard — positioned as a more visualization-first alternative. community

Open questions / unverified

  • No genuine Reddit, Hacker News, X/Twitter, or LinkedIn primary discussion was found. A targeted r/ClaudeAI search returned nothing indexed. The task asked to document community sentiment from these venues; I could not, and am declining to fabricate it. The substantive independent signal is concentrated in roborhythms + GitHub issues.
  • The "sharply divided community sentiment on contribution credit" / drama claim is NOT supported by primary sources. roborhythms asserts it, but the one attribution-related issue I could read — #799 — is a third party being scrupulously respectful about crediting Graphify upstream, with zero comments and a clean close. That is the opposite of drama. Treat roborhythms' characterization as an unverified secondhand claim. unverified claim vs. community
  • No maintainer explanation found for the net-token-increase reports (#580); whether v0.8.29's ~47% context reduction actually fixes it is unverified — no independent re-test post-fix exists.
  • The 71.5x-on-52-files Medium claim is unverified and contradicts roborhythms' tested "<100 files ≈ 1–3x." unverified claim
  • pypistats.org rate-limited during checking; download total is from pepy.tech only (single source, but a primary endpoint).

Sources