cc-os/docs/graphify/00-README.md

# Graphify — Setup & Best-Practices Guide

A practical handbook for setting up and using **Graphify** ([safishamsi/graphify](https://github.com/safishamsi/graphify),
PyPI package `graphifyy`) across many projects at once — code, documents, and a personal knowledge base.
Graphify turns a folder of mixed content into a queryable **knowledge graph** that your AI coding assistant
reads instead of re-reading the whole corpus every session.

The guide is distilled from a creator interview (a marketing/influencer piece — see provenance below),
then verified and corrected against the official GitHub repository and supplemented with independent sources.

## Read in this order

1. **[01-overview-concepts.md](01-overview-concepts.md)** — What Graphify is and the mental model:
   knowledge-graph-of-everything, god nodes, confidence tags, neuro-symbolic framing, why a graph beats
   plain file search and Obsidian. **Start here.**
2. **[02-installation-setup.md](02-installation-setup.md)** — Install (`uv tool install graphifyy`),
   register with your assistant, first `graphify .` run, and how to avoid a first-run token blowout.
3. **[03-ingesting-code-ast.md](03-ingesting-code-ast.md)** — Indexing **code** with tree-sitter AST:
   free, no LLM, 33 languages, multi-repo. The core rule: *AST for code, save the model for documents.*
4. **[04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md)** — Indexing **documents & a personal
   KB**: PDF/docx/xlsx/images, audio/video transcription, YouTube, Google Workspace; when documents need a model.
5. **[05-local-models-and-backends.md](05-local-models-and-backends.md)** — **Backends**: local Ollama/SLM
   vs. cloud (Bedrock, Claude, Gemini, OpenAI, …), env vars, privacy, and choosing on cost/quality/privacy.
6. **[06-querying-and-god-nodes.md](06-querying-and-god-nodes.md)** — The highest-leverage skill:
   ask for **god nodes first**, then scalpel down; *prompt the graph, don't make the LLM read the corpus.*
7. **[07-token-economics-and-updates.md](07-token-economics-and-updates.md)** — Where savings really come
   from (honestly), cost levers, and keeping the graph fresh with `--update` (SHA-256 + dedup) and hooks.
8. **[08-workflows-and-use-cases.md](08-workflows-and-use-cases.md)** — End-to-end playbooks: onboarding,
   bug tracing, AI-slop audits, the cross-project "second brain," PR impact analysis.
9. **[09-best-practices-checklist.md](09-best-practices-checklist.md)** — The do/don't reference card +
   command quick-reference + setting-up-across-many-projects mini-guide. **Keep this one open while working.**
10. **[external-tips.md](external-tips.md)** — Independent/community tips, gotchas with issue links, and an
    even-handed look at the token-savings debate.

## One-paragraph summary

Install with `uv tool install graphifyy` (the package is `graphifyy` — double-y, a temporary name — but the
command is `graphify`), then `graphify install` to register it with Claude Code (or Codex/Cursor/Gemini/OpenCode).
Run `graphify .` on a folder; it writes `graphify-out/` containing an interactive `graph.html`, a `GRAPH_REPORT.md`
(whose top lists the **god nodes** — the most-connected concepts), and a `graph.json`. **Code** is parsed locally
with tree-sitter AST — free, no tokens, 33 languages. **Documents, images, and media** need a model backend for
semantic extraction; point that at **local Ollama** to keep it free and private, or at a cloud model. The retrieval
discipline that delivers the savings: ask for god nodes first, then query the graph (`graphify query`/`path`/`explain`)
rather than dumping the whole corpus into context. Always `graphify ... --update` when adding data so it merges
(SHA-256 hashing + dedup) instead of rebuilding. Fold many repos into one graph with `graphify global add`.

## How this guide was built — provenance & honesty

This matters because you're going to *run* these commands. Each substantive claim in the docs is tagged inline:

| Tag | Meaning |
|-----|---------|
| `[github]` | Verified against the official repository README (see version note below) — **most trustworthy** |
| `[interview]` | Stated only in the creator interview — unconfirmed framing or claim |
| `[community](url)` | From an independent third-party source, with link |
| `[site]` / `[pypi]` | From graphifylabs.ai or the PyPI listing |
| `[unverified claim]` | Asserted (often marketing) but not confirmed against a primary source |

**Sources, and how much to trust them:**

- **The interview** (`graphify-interview` in the repo root) is a hype/marketing influencer piece with the creator
  (Safi Shamsi) and noisy auto-transcription. It's a good source of *intent and workflow advice* but a poor source
  of *facts* — names, commands, and numbers are garbled. We treated it as a starting hypothesis, not ground truth.
- **The GitHub repo** is the authority. We anchored on the **v0.8.30 release README** (published 2026-06-02, the
  latest published release as of 2026-06-03; a `v1.0.0` tag also exists but isn't a published release). Disputed
  flags were settled by grepping the *raw* README bytes, not summaries.
- **The official site** (https://graphifylabs.ai/) returned **HTTP 403** to automated fetches, so nothing was
  verified directly from it; site-only claims are flagged.

**Corrections we made to the interview's claims (and why they're in the docs):**

- **"AST for code, LLM for documents"** holds — but the interview's claim that **shell scripts aren't AST-supported**
  is outdated; v0.8.30 lists `.sh`/`.bash`/`.ps1` among its 33 tree-sitter languages.
- **Package name** is `graphifyy` (double-y), not `graphify`, on PyPI.
- **Flag set is version-dependent.** `--token-budget`, `--max-concurrency`, `--api-timeout`, `--budget`, and
  `--force` are all real in **v0.8.30** (grep-verified) but absent from the shorter `main`-branch README. If your
  build differs, confirm with `graphify --help`. Note: `--budget` caps *query answer* size; `--token-budget` sets
  *extraction* chunk size — different flags, different stages.
- **"Meetings / Slack / OneNote connectors"** are roadmap or belong to a separate product, **not** shipped in
  Graphify today.

**On the headline token-savings numbers (70x / 90x / 71.5x):** treat them as corpus-dependent marketing, not a
guarantee. Independent testing (roborhythms) reproduced large-monorepo wins but measured a realistic **~1–49x**,
with **net-negative** results on small repos (the mandatory "read the graph first" preamble can cost more than it
saves on <100-file projects — see GitHub issue #580). The creator himself says there's "no floor, no ceiling."
**Measure your own with `graphify benchmark`.** (Separately, the repo's *popularity* claims under-sold reality:
third-party trackers showed ~58K stars and ~1.28M downloads as of 2026-06-03 — bigger than the interview's figures.)

**Caveat — Graphify moves fast.** Multiple releases shipped *per day* during early June 2026. Commands and flags
here reflect v0.8.30; if something doesn't match, run `graphify --help` and prefer the latest release README.

_Last updated: 2026-06-03 · anchored to Graphify v0.8.30_