--- summary: A scannable do/don't checklist, command quick-reference card, multi-project setup guide, and common-mistakes list for using Graphify v0.8.30 correctly and efficiently. tags: - type/reference - tool/graphify - scope/global - domain/knowledge-graphs - domain/llm source: cc-os date: 2026-06-08 --- # 09 — Best-Practices Checklist & Quick Reference The page to keep open while using Graphify (v0.8.30): a scannable do/don't list, a command quick-reference, a "many projects" setup mini-guide, and the common mistakes to avoid. Detail lives in the sibling docs — this card cross-links to them. > Provenance tags: `[interview]` (creator's intent/sales claims), `[github]` (verified repo facts), `[community]` (third-party), `[unverified claim]`. --- ## Do / Don't **Do** - **Index code freely — it's local AST, no tokens.** Code (33 languages, tree-sitter) parses on your machine with no model calls. Run `graphify .` on any repo without fear. `[github]` `[interview]` — see [03-ingesting-code-ast.md](03-ingesting-code-ast.md) - **Reserve the model (tokens) for documents/images/audio/video only.** This split is the #1 cost rule. `[interview]` — see [04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md) - **Use a local backend (`--backend ollama`) for documents** to keep extraction free and private. `[interview]` — see [05-local-models-and-backends.md](05-local-models-and-backends.md) - **Ask for god nodes FIRST, then scalpel down.** Read the top of `GRAPH_REPORT.md` for the architecture spine, then `explain` / `path` / bounded `query` into specifics. `[interview]` — see [06-querying-and-god-nodes.md](06-querying-and-god-nodes.md) - **Prompt the graph, don't make the LLM read the corpus.** The graph IS the memory; have the assistant *extract from* it, not traverse it. `[interview]` - **Always `--update` when adding data.** SHA-256 hashing + dedup re-process only changed files and merge in, instead of rebuilding. `[interview]` `[github]` — see [07-token-economics-and-updates.md](07-token-economics-and-updates.md) - **Split large corpora and re-ingest in pieces** rather than dumping one giant chunk — cheaper and less hallucination/dilution. `[interview]` - **Tune for local/small models:** smaller `--token-budget` (chunk size), lower `--max-concurrency`, raise `--api-timeout` if it stalls. `[github]` - **Automate freshness for code:** `graphify hook install` (commit hook) or `--watch` — both AST-only, free. `[github]` - **Measure your own savings with `graphify benchmark`** instead of trusting any headline multiplier. `[github]` **Don't** - **Don't quote a token multiplier as a promise.** "70x / 90x / 71.5x" are corpus-dependent marketing figures; independent testing shows ~1–49x, and net-*negative* on small repos (<100 files ≈ 1–3x; some users measure *more* tokens). Say "measure with `graphify benchmark`." `[unverified claim]` `[community]` — see [07](07-token-economics-and-updates.md) and [external-tips.md](external-tips.md) - **Don't run your first build on a big doc pile with a cloud backend** — that's the way to burn your daily limit (one user burned theirs + $25–30 extra). Start on code, then add docs locally. `[interview]` - **Don't expect `graphify query "god nodes"` to return the ranking** — `query` is semantic search; the structural god-node list lives at the top of `GRAPH_REPORT.md`. `[github]` - **Don't confuse `--budget` with `--token-budget`.** `--budget N` caps a **query answer**; `--token-budget N` sets the **extraction chunk size**. Different stages. `[github]` - **Don't expect the commit hook (or `--watch`) to refresh docs** — they handle **code only**. Re-run `--update` on docs manually (they cost tokens). `[github]` - **Don't rebuild from scratch to add data** — use `--update`. Use `--force` only to overwrite/clear ghost nodes after deletions. `[github]` - **Don't treat Obsidian as a substitute.** It's a nice visual pairing, but it can't cluster or surface cross-community links the way Graphify does. `[interview]` — see [01-overview-concepts.md](01-overview-concepts.md) - **Don't get the package name wrong** — it's `graphifyy` (double-y), the binary is `graphify`. The single most common install mistake. `[community]` --- ## Command quick-reference (v0.8.30) > **Invocation forms.** In-IDE uses the slash form (`/graphify ./path --update`) and borrows your session's model for docs. Headless uses `graphify extract ./path` and needs an explicit `--backend`. The `query` / `path` / `explain` verbs work both ways (drop the slash in a terminal; always use the no-slash form on Windows PowerShell). `[github]` **Install & register** ```bash uv tool install graphifyy # recommended (or: pip install graphifyy) graphify install # register the skill with your assistant graphify claude install # optional: make Claude consult the graph automatically ``` **Build / update** | Goal | Command | Cost | |---|---|---| | First build | `/graphify ./path` — or headless `graphify extract ./path --backend ollama` | code free; docs/images cost tokens | | Add / changed data | `/graphify ./path --update` | only changed files re-processed | | Rebuild, clear ghost nodes after deletions | `graphify extract . --force` (or `GRAPHIFY_FORCE=1`) | as a full rebuild | | Richer inference | `/graphify ./path --mode deep` | higher (more LLM passes) | | Auto-rebuild on commit (code only) | `graphify hook install` | free (AST) | | Live auto-rebuild (code only) | `/graphify ./path --watch` | free (AST) | | Measure savings | `graphify benchmark` | free | **Query (start at god nodes in `GRAPH_REPORT.md`, then drill down)** | Goal | Command | |---|---| | Semantic search, bounded answer | `graphify query "..." --dfs --budget 1500` | | Connect two named nodes | `graphify path "A" "B"` | | Deep-dive one node | `graphify explain "Node"` | | Visual call-flow | `graphify export callflow-html` | | Re-cluster (free, no re-extract) | `graphify cluster-only . --resolution 1.5` | | De-noise god-node ranking | `... --exclude-hubs 99` | | PR impact / review queue | `graphify prs` (`prs 42`, `--triage`, `--conflicts`) | **Local-model tuning flags** (extraction stage; see [05](05-local-models-and-backends.md)) ```bash graphify extract ./docs --backend ollama \ --token-budget 4000 --max-concurrency 2 --api-timeout 900 # Ollama env: OLLAMA_BASE_URL, OLLAMA_MODEL, # GRAPHIFY_OLLAMA_NUM_CTX, GRAPHIFY_OLLAMA_KEEP_ALIVE ``` **Outputs** land in `graphify-out/`: `graph.html`, `GRAPH_REPORT.md`, `graph.json`, `cache/`. Backends: `ollama` (local), `bedrock`, `claude`, `gemini`, `openai`, `deepseek`, `kimi`. --- ## Setting up across many projects (code + docs + KB) The pattern: **one graph per project, folded into one global view.** Keeps each `--update` cheap and isolated while giving you a single place to query across everything. Full playbook in [08-workflows-and-use-cases.md](08-workflows-and-use-cases.md) (Playbook 4) and the global-graph mechanics in [03-ingesting-code-ast.md](03-ingesting-code-ast.md). 1. **Build a graph in each repo / doc folder / KB vault.** Code is free (AST); route documents through a local backend to keep them free and private (see [05-local-models-and-backends.md](05-local-models-and-backends.md)): ```bash /graphify . # in a code repo (free) graphify extract ./notes --backend ollama # in a docs/KB folder (local model) ``` 2. **Register each into the global graph** (lives at `~/.graphify/global.json`): ```bash graphify global add graphify-out/graph.json my-api graphify global add graphify-out/graph.json my-notes graphify global list # node/edge counts per repo graphify global remove my-api # unregister ``` 3. **Set a freshness cadence by content type:** - **Code → automate:** `graphify hook install` per repo (rebuilds on commit, free). `[github]` - **Docs/KB → on demand:** `--update` deliberately after adding/editing material (costs tokens; the hook won't touch docs). `[github]` - **Re-register after a doc refresh** so the global view picks up new nodes: `graphify global add graphify-out/graph.json my-notes`. 4. **Pull in external knowledge** (papers, lectures — videos transcribed locally): ```bash /graphify add https://arxiv.org/abs/1706.03762 /graphify add ``` --- ## Common mistakes - **Wrong package name.** Install `graphifyy` (double-y); the binary is `graphify`. `[community]` - **First run = big docs + cloud backend → token burn.** Start on code (free), add docs with a local Ollama backend. `[interview]` - **Expecting `query` to return god nodes.** It's semantic search — read the ranking at the top of `GRAPH_REPORT.md`. `[github]` - **Mixing up `--budget` (query answer) and `--token-budget` (extraction chunk).** `[github]` - **Expecting the commit hook / `--watch` to refresh docs.** Code only; re-run `--update` on docs yourself. `[github]` - **Stale-node drift.** `--update` is known to leak stale nodes (removed symbols aren't always pruned); use `--force` to rebuild clean when the graph drifts. `[community]` `[github]` - **Quoting a savings multiplier.** Corpus-dependent — measure your own with `graphify benchmark`. `[unverified claim]` --- Index: [00-README.md](00-README.md) · Concepts: [01-overview-concepts.md](01-overview-concepts.md) · Install: [02-installation-setup.md](02-installation-setup.md) · Community/skeptical notes: [external-tips.md](external-tips.md)