12 KiB

Raw Blame History

Workflows & Use Cases

End-to-end playbooks for running Graphify as a one-person operation across code, documents, and a personal knowledge base. Every command below is verbatim from the v8 README; concepts are covered in the sibling docs and cross-linked rather than re-explained.

Provenance: commands are tagged [github] (verified from the v8 README). Claims from the creator interview are tagged [interview] and headline savings numbers are sales claims, not benchmarks. See 00-README for the tagging scheme.

Skill vs. CLI prefix: commands written /graphify ... run through the IDE skill (your assistant's model provides the LLM calls for documents — no separate API key). Commands written graphify ... are the plain CLI. graphify extract ... is the headless form used in CI or when you want to pin a backend explicitly. [github]

Playbook 1 — Onboard fast to an unfamiliar codebase

For a new hire, contractor, or your own first hour in a repo you inherited. The interview frames this as the flagship use case: replace days of code-spelunking and Slack pings with one map. [interview]

Map the whole repo. Code is parsed locally via AST — no API calls, no token cost. [github]
```
/graphify .
```
This writes graphify-out/graph.html, graphify-out/GRAPH_REPORT.md, and graphify-out/graph.json. [github]
Read the report first, not the source. Open graphify-out/GRAPH_REPORT.md for architectural highlights. [github]
God nodes first. Ask the graph for its most-connected concepts before reading any file — these are the architectural chokepoints "everything flows through." [github] See 06-querying-and-god-nodes for the god-node querying pattern.
```
/graphify query "what are the god nodes / most connected components?"
```
Heuristic from the creator: a huge pile of god nodes signals weak cohesion or a structural mess; a modest set means the architecture is sane. [interview]

Trace the architecture from those hubs outward.

/graphify explain "AuthService"
/graphify query "what connects auth to the database?"

Generate a readable architecture page with Mermaid call-flow diagrams to skim the system visually.
```
graphify export callflow-html
```
[github]

ROI framing (sales claim): the creator pitches this as replacing a $150/hr engineer's multi-day ramp-up with a few free minutes. Treat the dollar figure as illustrative. [interview]

Playbook 2 — Fix a bug / ticket by tracing dependencies

You have a ticket ("users hitting an error on the backend") and need the blast radius before you touch code.

Make sure the graph reflects current HEAD (see Playbook 4 for keeping it fresh):
```
/graphify --update
```
[github]
Locate the suspect component via god nodes / a targeted query, then expand its neighborhood:
```
/graphify explain "RateLimiter"
```
[github]
Trace the dependency chain between the failing area and its likely root using shortest path:
```
/graphify path "UserService" "DatabasePool"
```
This returns the shortest connection between two entities — the chain of files/functions the bug can propagate through. [github]

Confirm the blast radius before editing:

/graphify query "what depends on DatabasePool?"

Query the graph, don't dump the corpus. Ask the assistant to extract from the graph rather than read every file — the graph is your context. [interview] Token mechanics in 07-token-economics-and-updates.

Playbook 3 — Audit AI-generated "slop" / junk code

The creator's pitch for non-experts shipping AI-written code fast: map it, then let the graph surface what's wrong. [interview]

Map the suspect tree:
```
/graphify .
```
Look at god-node count as a smell test. An unusually large or sprawling set of god nodes points at poor cohesion — a hallmark of slop. [interview]
Hunt for orphans and dead ends — nodes with no meaningful connections often mean dead or duplicated code:
```
/graphify query "which components are disconnected or have no dependents?"
```
[github]
Use relationship confidence tags. Every inferred edge is marked EXTRACTED, INFERRED, or AMBIGUOUS, so you can tell what was found in the code vs. guessed — AMBIGUOUS clusters are good places to look for confusion. [github]
For shell scripts (no AST support yet): ingest them as documents so the model does a semantic extraction instead of AST parsing. [interview] The creator calls shell scripts "flat" and treats document-mode as the temporary workaround. Note .sh/.bash do appear in the v8 supported-extensions list [github], so behavior may have shifted since the interview — verify on your version.

Playbook 4 — Build a persistent "digital twin" / second brain

The cross-project setup you actually want: one queryable memory spanning your code repos, documents, and a personal KB, kept fresh over time. The creator's framing is a "digital twin" that "gets smarter with time" via incremental updates. [interview]

Recommended structure: many local graphs, one global view

Don't try to cram everything into a single monolithic extraction. Build a graph per project, then fold them into one cross-project global graph. This keeps each project's --update cheap and isolated while still giving you one place to query across everything. [github]

In each repo / doc folder / KB vault, build its own graph:
```
/graphify .            # in a code repo
/graphify ./notes      # in your personal KB / Obsidian vault
```
Code is free/local; documents and notes go through a model — use a local backend to keep this free and private (see Playbook 6 and 05-local-models-and-backends). [github] [interview]

graphify global add graphify-out/graph.json my-api
graphify global add graphify-out/graph.json my-notes
graphify global list      # see all registered repos + node/edge counts

The global graph lives at ~/.graphify/global.json. [github]

(Alternative one-step form) Extract and register in a single command:
```
graphify extract ./notes --global --as my-notes
```
[github]
Query across the whole twin via your normal query / path / explain calls, leaning on god nodes to navigate. [github] [interview]

Ingest cadence (keep the twin from going stale)

The user's real concern is assets going stale. Split the cadence by content type:

Code — automate it. Install the git hook once per repo so the graph rebuilds on every commit (AST only, no API cost), and graph.json auto-merges instead of conflicting:
```
graphify hook install
```
[github]
Docs / KB / papers — refresh on demand. These need a model call, so run them deliberately after you add or change material. --update re-extracts only changed files using SHA-256 hashing, so it resumes where it left off rather than rebuilding: [interview] [github]
```
/graphify --update            # or: /graphify ./notes --update
```
Re-register after a doc refresh so the global view picks up the new nodes:
```
graphify global add graphify-out/graph.json my-notes
```
Ingest in splits, not one giant dump. The creator recommends splitting a large repo or document set and re-ingesting in pieces rather than pushing the whole corpus in one shot — it merges in more cleanly and avoids context dilution. [interview]

Pulling external knowledge into the brain

Add papers and videos straight into a graph (videos transcribed locally via faster-whisper): [github]

/graphify add https://arxiv.org/abs/1706.03762
/graphify add <youtube-url>
/graphify add https://... --author "Name" --contributor "Name"

[interview] describes this as turning a Stanford lecture or any video/audio into a queryable section-by-section map instead of re-watching it.

Playbook 5 — PR impact analysis

For reviewing your own or a team's pull requests with graph-aware impact. Requires the GitHub CLI auth your repo already uses.

See the dashboard — every open PR with CI state, review status, worktree mapping, and graph impact:
```
graphify prs
```
Deep-dive a specific PR's blast radius:
```
graphify prs 42
```
Let the graph rank your review queue (auto-detects backend from env):
```
graphify prs --triage
```
Spot merge-order risk — PRs touching the same graph communities are likely to conflict:
```
graphify prs --conflicts
```

Scope it when you have many branches:

graphify prs --base main          # only PRs targeting main
graphify prs --worktrees          # worktree → branch → PR mapping
graphify prs --repo owner/repo    # a different repo

All [github]. To pin the triage backend (e.g. keep it local/cheap):

GRAPHIFY_TRIAGE_BACKEND=ollama graphify prs --triage

[github]

Playbook 6 — The creator's own day-to-day workflow

The distilled habit the creator described for himself. [interview]

Local LLM for documents. Extract docs/notes with Ollama so it's free and stays on your machine — no cloud, no per-token cost: [interview] [github]

graphify extract ./docs --backend ollama

Code never needs this (it's local AST already). Tuning for small GPUs:

GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama
GRAPHIFY_OLLAMA_KEEP_ALIVE=0 graphify extract ./docs --backend ollama   # unload after each chunk
graphify extract ./docs --backend ollama --token-budget 4000            # smaller chunks for local models

[github] Full backend setup in 05-local-models-and-backends.

God nodes first. Always open with the most-connected concepts to get the map before drilling in. [interview]
Query the graph, not the corpus. Prompt the assistant to extract from the graph — the graph is the context/memory. Never ask the LLM to read the whole corpus again. [interview]
Always --update when ingesting new material so a later query doesn't force a full re-read. [interview]
```
/graphify --update
```
Lock the query-first behavior in. Register Graphify with your assistant so it consults the graph before grepping/reading files:
```
graphify install            # or: graphify claude install
```
[github] The creator notes he's working toward hard-wiring "go to the graph first" into the agent's behavior. [interview]

Token-savings note

The interview's headline figures — "71.5x" in the README, with reports of "20x to 90x" from users — are sales claims and explicitly described as corpus-dependent with "no ceiling or floor." Do not treat them as guarantees. [interview] See 07-token-economics-and-updates.

Open questions / unverified

Shell-script handling drift. The interview says shell scripts aren't AST-supported and must be ingested as documents, but the v8 supported-extensions list includes .sh/.bash. [github] The document-mode workaround in Playbook 3 may be obsolete on current versions — confirm against your installed build. [unverified claim]
graphify-out/ reuse across projects in the global graph. Each graphify . writes to a local graphify-out/; the exact path you register with graphify global add matters. Confirm whether re-running global add with the same name replaces or appends — not stated in the README. [unverified claim]
/graphify add for KB sources (arxiv/youtube) is documented [github], but whether added external sources are automatically included when you fold the project into the global graph is unverified. [unverified claim]
Self-learning / domain-adapting "smarter over time" layer and Slack/Notion/meeting connectors are described by the creator as in-progress/future, not shipped in v8. [interview] Do not build a workflow that depends on them yet.
Official site (graphifylabs.ai) blocks plain fetch (403); documented workflows here are anchored on the v8 README rather than the marketing site.

12 KiB Raw Blame History