--- summary: Step-by-step guide to installing Graphify, registering it with Claude Code and other assistants, running a first graph safely, and avoiding the token-burn trap on a first document ingestion run. tags: - type/howto - tool/graphify - scope/global - domain/knowledge-graphs - domain/llm source: cc-os date: 2026-06-08 last_updated: 2026-07-14 --- # 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](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`: ```bash # 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: ```bash 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](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: ```bash 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): ```bash 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](05-local-models-and-backends.md). Useful first-run variants `[github]`: ```bash 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](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]` ### How graphify resolves ignore files (verified against installed source) Read directly from the installed `graphifyy` 0.8.31 package, `graphify/detect.py` — `_load_graphifyignore()` (lines 682–717) and `_is_ignored()` (720+). These supersede the widely-repeated claim that **"graphify does not honor `.gitignore`"**, which is now stale. `[source]` 1. **It DOES fall back to `.gitignore`.** Per directory, graphify prefers `.graphifyignore`; if that file is absent it reads that directory's `.gitignore` instead (`detect.py:707–711`, added for upstream issue #945). A repo with a `.gitignore` and no `.graphifyignore` is therefore **not** unprotected. `[source]` 2. **The real trap is shadowing, not blindness.** The lookup is `if .graphifyignore not exists: use .gitignore` — an **either/or per directory, never a merge**. Adding a `.graphifyignore` to a directory makes graphify stop reading that directory's `.gitignore` entirely. So a short, partial `.graphifyignore` can *silently re-expose* everything `.gitignore` was keeping out (`node_modules/`, `dist/`, build caches) — the exact blow-up a `.graphifyignore` is usually added to prevent. **A `.graphifyignore` must be self-sufficient: it replaces `.gitignore`, it does not extend it.** `[source]` 3. **Only the ancestor chain is consulted.** It walks from the nearest VCS root *down to the scan root* — ancestors of where you point it, not a recursive descent. Running `graphify extract .` at a repo root reads **exactly one** ignore file (the root's). Nested per-subdirectory `.gitignore` files deeper in the tree are **never** honored — unlike git itself. `[source]` 4. **Dialect is true gitignore**, not fnmatch: last-match-wins, `!` negation, and gitignore's parent-exclusion rule (a `!` cannot re-include a file whose ancestor directory is already excluded) — `_parse_gitignore_line()` (645–666), `_is_ignored()` (720+). `[source]` --- ## 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 1. **Check the directory:** `graphify-out/` exists and contains `graph.html`, `GRAPH_REPORT.md`, and `graph.json`. `[github]` 2. **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](06-querying-and-god-nodes.md). 3. **Watch the token benchmark:** Graphify prints a token benchmark automatically after every run, showing tokens-per-query vs. reading the raw files. `[github]` 4. **Open the graph:** open `graph.html` in a browser to click through nodes and communities. `[github]` 5. **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](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](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](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 ```bash # 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](05-local-models-and-backends.md) (keep document ingestion free with Ollama) and [07-token-economics-and-updates.md](07-token-economics-and-updates.md) (incremental updates and where the savings come from). Concept refresher: [01-overview-concepts.md](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](04-ingesting-docs-knowledge.md) and [05-local-models-and-backends.md](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.