16 KiB

Raw Blame History

summary

Installation & First Run

How to install Graphify, register it with Claude Code (and other assistants), run your first graph, and confirm it worked — without accidentally burning through your token/usage limit on the first try.

Provenance tags used throughout: [github] = official GitHub README (anchored to the v0.8.30 release README, the comprehensive current version — fetched 2026-06-03; the shorter main-branch README omits some flags), [pypi] = PyPI page, [site] = graphifylabs.ai, [interview] = creator interview (sales/marketing context, treat as claims), [community] = third-party source, [unverified claim] = stated somewhere but not confirmed against a primary source.

1. Prerequisites

Requirement	Notes
Python 3.10+	Required. Check with `python --version`. `[github][pypi]`
An AI coding assistant	Claude Code is the primary target; Codex, OpenCode, Cursor, and Gemini CLI are also supported. `[github]`
`uv` or `pipx` (recommended)	Either gives you isolated tool installs and puts `graphify` on your PATH automatically. `[github]`
Ollama (optional)	Only needed if you want a local LLM backend for documents. See 05-local-models-and-backends.md. `[github]` (verified facts)
`[google]` extra + Google auth (optional)	Only for the Google Workspace connector. `[github]` (verified facts)
AWS Bedrock access (optional)	Only if you want a cloud LLM backend via `--backend bedrock`. `[github]` (verified facts)

Code ingestion is done locally and needs no LLM. Code files are parsed with a tree-sitter AST (abstract syntax tree) pass — no file contents leave your machine, no API calls. [github] Semantic extraction of docs, papers, and images is what calls a model (your assistant's provider, or a local backend). [github] Video/audio is transcribed locally with Whisper. [github] This split is the single most important thing to understand before your first run (see §6).

2. Install

The PyPI package is named graphifyy (double y) — the plain graphify name on PyPI is an unrelated package. The CLI command you type is still graphify. [github]

Install and register in one line. The README leads with uv:

# Recommended — works on Mac and Linux with no PATH setup needed
uv tool install graphifyy && graphify install
# or with pipx
pipx install graphifyy && graphify install
# or plain pip
pip install graphifyy && graphify install

[github]

Why uv (or pipx) is recommended: both put the CLI in a managed location that's automatically on your PATH, so you avoid the graphify: command not found problem. With plain pip you may have to add ~/.local/bin (Linux) or ~/Library/Python/3.x/bin (Mac) to your PATH yourself, or run python -m graphify instead. [github]

Optional extras

Install feature groups with bracket syntax. Confirmed in the README's file-type table:

pip install "graphifyy[office]"   # .docx / .xlsx ingestion
pip install "graphifyy[video]"    # video/audio transcription (faster-whisper + yt-dlp)
pip install "graphifyy[mcp]"      # MCP stdio server (graphify.serve)

[github] PDFs and images are supported out of the box (no extra needed). [github]

The Google Workspace connector uses a [google] extra (uv tool install "graphifyy[google]", then gws auth login, run with --google-workspace), verified in the v0.8.30 README and detailed in 04-ingesting-docs-knowledge.md. [github] Other extra names seen on the PyPI listing (pdf, neo4j, anthropic, all, …) should be confirmed against the PyPI page or graphify --help before you rely on them. [pypi]/[unverified claim]

3. Register with your assistant

graphify install (already chained into the install command above) drops the platform-specific skill manifest into your assistant's config directory so you can invoke /graphify from inside the assistant. For Claude Code on Mac/Linux this is all you need. [github]

Target a specific assistant with --platform (or a per-platform subcommand). From the README's platform table [github]:

Platform	Install command
Claude Code (Linux/Mac)	`graphify install`
Claude Code (Windows)	`graphify install` (auto-detected) or `graphify install --platform windows`
Codex	`graphify install --platform codex`
OpenCode	`graphify install --platform opencode`
Gemini CLI	`graphify install --platform gemini`
GitHub Copilot CLI	`graphify install --platform copilot`
Cursor	`graphify cursor install`
Aider	`graphify install --platform aider`

(Full list in the README also covers VS Code Copilot Chat, Trae, Kiro, Hermes, Factory Droid, OpenClaw, and Google Antigravity.) [github]

Codex calls skills with $ instead of /, so type $graphify . there. Codex also needs multi_agent = true under [features] in ~/.codex/config.toml for parallel extraction. [github]

Make the assistant always use the graph (recommended)

Registering the skill lets you call /graphify on demand. To make your assistant consult the graph automatically before grepping files, run the always-on installer after you've built a graph in a project:

graphify claude install   # Claude Code: writes a CLAUDE.md section + a PreToolUse hook

For Claude Code this adds a CLAUDE.md note telling Claude to read graphify-out/GRAPH_REPORT.md before architecture questions, plus a PreToolUse hook (in settings.json) that fires before Glob/Grep and reminds Claude to navigate via the graph. Equivalent per-platform commands exist (graphify codex install, graphify gemini install, graphify cursor install, etc.); uninstall with the matching ... uninstall. [github]

Manual install (no package manager)

The README documents a curl-based fallback that copies the skill into ~/.claude/skills/graphify/SKILL.md and adds a trigger line to ~/.claude/CLAUDE.md. Use this only if you can't use uv/pipx. [github]

4. First run

From inside your assistant (Claude Code, etc.):

/graphify .

Or from a plain shell (on Windows/PowerShell, drop the slash — / is read as a path separator):

graphify .

This reads the files in the target folder, builds the knowledge graph, and writes everything into a graphify-out/ directory. [github] You can point it at any folder — a codebase, a notes directory, a folder of papers. [github]

Three invocation contexts — know which one you're in [github]:

Inside your AI assistant: /graphify . — semantic extraction uses your IDE session's model (no API key needed).

Windows / plain shell: graphify . (no leading slash) — same skill.

Headless / CI: graphify extract ./path (build) and graphify update ./path (incremental) — these run standalone and need a backend: an API key (ANTHROPIC_API_KEY, GEMINI_API_KEY, …) or a local --backend ollama. Code (AST) is always free; only documents need the backend. See 05-local-models-and-backends.md.

Useful first-run variants [github]:

graphify ./docs              # run on a specific folder
graphify . --update          # re-extract only changed files, merge into existing graph
graphify . --no-viz          # skip the HTML, just produce the report + JSON
graphify . --mode deep       # more aggressive INFERRED edge extraction

A --force flag (or GRAPHIFY_FORCE=1) forces a full rebuild and overwrites the graph even when it ends up with fewer nodes — use it after a refactor that deleted files, to clear lingering "ghost" nodes. Verified in the v0.8.30 README. [github] See 07-token-economics-and-updates.md.

Add a .graphifyignore file (same syntax as .gitignore) at your repo root to exclude folders like node_modules/, dist/, or generated files from the graph. [github]

5. What you get and where it lands

Everything is written under graphify-out/ in the directory you ran against. From the README's literal output tree [github]:

graphify-out/
├── graph.html       interactive graph — open in any browser, click nodes, search, filter by community
├── GRAPH_REPORT.md  god nodes, surprising connections, suggested questions
├── graph.json       persistent graph — query weeks later without re-reading files
└── cache/           SHA256 cache — re-runs only process changed files

The three headline outputs map to the verified "interactive HTML graph, markdown report, JSON graph file": graph.html, GRAPH_REPORT.md, graph.json. [github]

Optional extra outputs are opt-in via flags, not produced by default: --obsidian writes an Obsidian vault, --wiki writes index.md + per-community articles, --svg writes graph.svg, --graphml writes graph.graphml, --neo4j writes cypher.txt. Video/audio runs also create graphify-out/transcripts/. [github]

Confirming it worked

Check the directory: graphify-out/ exists and contains graph.html, GRAPH_REPORT.md, and graph.json. [github]
Open the report: GRAPH_REPORT.md lists the god nodes (highest-degree concepts), surprising connections, and 4–5 suggested questions. If you see god nodes, extraction succeeded. [github] See 06-querying-and-god-nodes.md.
Watch the token benchmark: Graphify prints a token benchmark automatically after every run, showing tokens-per-query vs. reading the raw files. [github]
Open the graph: open graph.html in a browser to click through nodes and communities. [github]
Sanity-check the CLI: graphify --help confirms the binary is on your PATH and lists available commands/flags. [unverified claim]

On a tiny corpus (a handful of files) the token reduction may be ~1x — that's expected. At that size the value is structural clarity, not compression; reductions scale with corpus size. [github] More on this in 07-token-economics-and-updates.md.

6. Avoid blowing your token limit on the first run

This is the #1 new-user mistake. In the interview, a user described running Graphify cold and burning through their entire daily limit plus ~$25–30 extra on top of a $100/mo Claude plan. [interview]

The cause: pointing Graphify at a big pile of documents and letting it call a cloud model (your assistant's provider) to extract every chunk. The fix is to understand what actually costs tokens:

Code → local AST, free. Code parsing uses tree-sitter AST locally with no model calls and no file contents leaving your machine. Run it on codebases freely. [github][interview]
Docs / papers / images → model, costs tokens. Only these go to a model for semantic extraction. [github] To make that free too, point the document backend at Ollama (a local small language model). [interview] (verified facts: --backend ollama) See 05-local-models-and-backends.md.
The first build costs tokens; queries are where you save. The initial extraction pays the token cost; every later query reads the compact graph instead of raw files, and the SHA256 cache means re-runs only re-process changed files. [github]
Use --update, not full rebuilds. When adding files later, re-run with --update so the cache reuses prior work instead of starting fresh. [interview][github] See 07-token-economics-and-updates.md.
Split large doc sets and re-ingest in pieces rather than dumping one giant chunk in a single run. [interview]

Practical first run: start on a code folder (free), confirm the graph looks right, then add documents with a local Ollama backend before scaling up.

7. Platform notes

macOS / Linux: uv tool install graphifyy or pipx install graphifyy both put graphify on your PATH with no setup. If you used plain pip and get graphify: command not found, add ~/.local/bin (Linux) or ~/Library/Python/3.x/bin (Mac) to your PATH, or run python -m graphify. [github]

Windows: Plain-pip scripts land in %APPDATA%\Python\PythonXY\Scripts — add that to your PATH, or just use uv/pipx. For Claude Code on Windows, graphify install auto-detects the platform (or use --platform windows). [github]

WSL / Ubuntu: Ubuntu ships python3, not python. For the MCP server path, install into a project venv to avoid PEP 668 conflicts: python3 -m venv .venv && .venv/bin/pip install "graphifyy[mcp]". [github]

8. Copy-pasteable quickstart

# 1. Prereqs: Python 3.10+ and uv (or pipx). Check Python:
python --version

# 2. Install Graphify + register the skill (package is "graphifyy" with double y;
#    command stays "graphify"). Recommended — no PATH setup on Mac/Linux:
uv tool install graphifyy && graphify install
#   or: pipx install graphifyy && graphify install
#   other assistants: graphify install --platform codex   (Cursor: graphify cursor install)

# 3. (Optional) make the assistant always consult the graph before grepping:
graphify claude install

# 4. First run — start with a CODE folder (AST parsing is free, no LLM):
graphify .

# 5. Confirm it worked:
ls graphify-out/                 # expect graph.html, GRAPH_REPORT.md, graph.json
#   open graphify-out/GRAPH_REPORT.md  -> check the god nodes
#   open graphify-out/graph.html       -> explore the graph

# 6. For DOCUMENTS, use a local model so you don't burn tokens — see doc 05.
#   Then add incrementally:
graphify ./docs --update

Next: 05-local-models-and-backends.md (keep document ingestion free with Ollama) and 07-token-economics-and-updates.md (incremental updates and where the savings come from). Concept refresher: 01-overview-concepts.md.

Open questions / unverified

README version skew (resolved). The repo ships two READMEs: a short main-branch one (leads with pip install, omits several flags) and the comprehensive v0.8.30 release README (leads with uv tool install graphifyy && graphify install, documents the full flag set). This doc — and the rest of this guide — anchors on v0.8.30, the current release. If a doc page elsewhere disagrees, prefer the v0.8.30 release README, and confirm with graphify --help on your installed version.
[google] Workspace connector + --backend ollama/bedrock env vars (OLLAMA_BASE_URL, gws auth login, --google-workspace, etc.) are all in the v0.8.30 README. See 04-ingesting-docs-knowledge.md and 05-local-models-and-backends.md for exact syntax.
Some extra names (pdf, neo4j, anthropic, all) come from the PyPI listing; [office], [video], [mcp] are README-confirmed. Confirm others before relying on them.
graphify --help as the post-install sanity check is inferred convention, not explicitly documented. [unverified claim]
Output directory is graphify-out/ relative to the run target per the README's literal tree; whether it can be relocated is not documented here.

16 KiB Raw Blame History Unescape Escape