This is a personal fork of safishamsi/graphify, maintained independently by Vit129. Not affiliated with the original project, Graphify Labs, or Penpax (the original author's own commercial product built on top of graphify). It's a hard fork, not a PR queue back upstream — see What's different from upstream. Not published to PyPI; install from source (see Install).
Type /graphify in your AI coding assistant and it maps your entire project — code, docs, PDFs, images, videos — into a knowledge graph you can query instead of grepping through files.
Works in Claude Code, Codex, OpenCode, Kilo Code, Cursor, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat, Aider, Amp, OpenClaw, Factory Droid, Trae, Hermes, Kimi Code, Kiro, Pi, Devin CLI, and Google Antigravity.
/graphify .
That's it. You get three files:
graphify-out/
├── graph.html open in any browser — click nodes, filter, search
├── GRAPH_REPORT.md the highlights: key concepts, surprising connections, suggested questions
└── graph.json the full graph — query it anytime without re-reading your files
For a readable architecture page with Mermaid call-flow diagrams, run:
graphify export callflow-htmlThis fork started from safishamsi/graphify and has repeatedly adopted upstream's own v8 rewrite branch as its base over several months — verified down to commit author (affected.py, resolver_registry.py, symbol_resolution.py, and most of the rest of the shared package were written by upstream's own maintainer and contributors, not this fork). What follows is only what's built on top of that shared base, checked directly against upstream's current source (3140b2e, v0.9.6), not assumed:
Fork-only, confirmed absent from upstream entirely:
- A real query/pathfinding layer (
graphify/query.py) — BM25 scoring with camelCase/snake_case tokenization, a typo/abbreviation/fuzzy-substring correction cascade, query synonym expansion, an optional local-embedding last resort, andfind_path_with_disambiguation(retries every near-tied candidate pair, avoids degree-heavy hub nodes). Upstream'sserve.pystill resolves nodes with the older tiered_EXACT_MATCH_BONUSscorer and a barenx.shortest_pathwith no hub avoidance.--path/--source-path/--target-path/--contextflags onpath/explain/queryare part of this same layer. - 7 extra language/config extractors —
.css/.scss,.html/.htm,.yaml/.yml,.toml,.robot/.resource,.feature(Gherkin), Fish shell (54 tree-sitter grammars vs upstream's 36). - Opt-in value-coupling (
shares_value:<value>edges,value_coupling = true) for config-as-code repos where nothing an AST sees actually "calls" anything. - Per-project config +
update --all(graphify.toml/[tool.graphify],config.py). - Extra analysis & UX:
god_nodes(by="pagerank"),cross_cutting_nodes(),unreachable_functions(),GRAPH_SUMMARY.md, a 3D/lensgraph.htmlviewer, dated-backup pruning, Playwright/Jesttest()/describe()node synthesis. - CLI surface is otherwise the same, not larger — upstream's
v8-derived tree already ships the sameprs,reflect,global,merge-graphs,save-result, and all 23 per-platform install subcommands.
Upstream-only, not carried by this fork (some fixed here, most still open):
- The entire Obsidian/Canvas export pipeline (
graphify export obsidian) — this fork doesn't have it at all, by omission, not oversight. - Several extraction-correctness fixes not yet pulled in: Ruby
module/Struct.new/Class.newcontainer nodes, Kotlin interface-delegation edges, Apex multi-interfaceextends, TSnamespace/generator-function/import-equals nodes,.mts/.ctsrecognition. - Robustness fixes not yet pulled in: deterministic parallel-merge ordering, Windows long-path I/O, Office
--updatere-conversion, cached word-count detection. - Already fixed here, previously upstream-only: C# receiver-typed member-call resolution (#1609), two JS/TS cross-file phantom-edge bugs (#1638, #1659), and a symlink-containment security gap in file collection.
| Requirement | Minimum | Check | Install |
|---|---|---|---|
| Python | 3.10+ | python --version |
python.org |
| uv (recommended) | any | uv --version |
curl -LsSf https://astral.sh/uv/install.sh | sh |
| pipx (alternative) | any | pipx --version |
pip install pipx |
macOS quick install (Homebrew):
brew install python@3.12 uvWindows quick install:
winget install astral-sh.uvUbuntu/Debian:
sudo apt install python3.12 python3-pip pipx
# or install uv:
curl -LsSf https://astral.sh/uv/install.sh | shSource-only fork: the PyPI name
graphifyyis already taken by upstream's package (currently v0.9.5, a different, older codebase) —pip install graphifyyfrom PyPI does not get you this fork. Install straight from this repo instead; the CLI command is stillgraphify.
Step 1 — install the package from this repo:
# Recommended (isolated env; if 'graphify' isn't found after, run: uv tool update-shell):
uv tool install git+https://github.com/Vit129/graphify.git
# Alternatives:
pipx install git+https://github.com/Vit129/graphify.git
pip install git+https://github.com/Vit129/graphify.git # may need PATH setup — see note belowStep 2 — register the skill with your AI assistant:
graphify installThat's it. Open your AI assistant and type /graphify .
To install the assistant skill into the current repository instead of your user
profile, add --project:
graphify install --project
graphify install --project --platform codexProject-scoped installs write under the current directory, for example
.claude/skills/graphify/SKILL.md or .agents/skills/graphify/SKILL.md (plus a
references/ sidecar the skill loads on demand), and
print a git add hint for files that can be committed.
Per-platform commands that support project-scoped installs accept the same flag,
for example graphify claude install --project or graphify codex install --project.
PowerShell note: Use
graphify .not/graphify .— the leading slash is a path separator in PowerShell.
graphify: command not found?uv tool install/pipx installput thegraphifycommand in their tool bin dir (~/.local/bin). If your shell can't find it right after install — common on a fresh macOS + zsh setup — that dir isn't on yourPATHyet: runuv tool update-shell(orpipx ensurepath), then open a new terminal. With plainpip, add~/.local/bin(Linux) or~/Library/Python/3.x/bin(Mac) to your PATH, or runpython -m graphify.
Running with
uvx/uv tool runinstead of installing? Point--fromat the git repo, not a bare package name:uvx --from git+https://github.com/Vit129/graphify.git graphify install. Plainuvx graphify …fails (No solution found … no versions of graphify) becauseuv tool runreads the first word as a PyPI package name, and this fork isn't on PyPI.
Avoid
pip installon Mac/Windows if possible. The skill resolves Python at runtime fromgraphify-out/.graphify_python; if that points to a different environment than wherepipinstalled the package, you'll getModuleNotFoundError: No module named 'graphify'.uv tool installandpipx installisolate the package in their own env and avoid this entirely.
Git hooks and uv tool / pipx:
graphify hook installembeds the current interpreter path directly into the hook scripts at install time, so the post-commit hook fires correctly even in GUI git clients and CI runners where~/.local/binis not on PATH. If you reinstall or upgrade graphify, re-rungraphify hook installto refresh the embedded path.
| Platform | Install command |
|---|---|
| Claude Code (Linux/Mac) | graphify install |
| Claude Code (Windows) | graphify install (auto-detected) or graphify install --platform windows |
| CodeBuddy | graphify install --platform codebuddy |
| Codex | graphify install --platform codex |
| OpenCode | graphify install --platform opencode |
| Kilo Code | graphify install --platform kilo |
| GitHub Copilot CLI | graphify install --platform copilot |
| VS Code Copilot Chat | graphify vscode install |
| Aider | graphify install --platform aider |
| OpenClaw | graphify install --platform claw |
| Factory Droid | graphify install --platform droid |
| Trae | graphify install --platform trae |
| Trae CN | graphify install --platform trae-cn |
| Gemini CLI | graphify install --platform gemini |
| Hermes | graphify install --platform hermes |
| Kimi Code | graphify install --platform kimi |
| Amp | graphify amp install |
| Agent Skills (cross-framework) | graphify install --platform agents (alias --platform skills) |
| Kiro IDE/CLI | graphify kiro install |
| Pi coding agent | graphify install --platform pi |
| Cursor | graphify cursor install |
| Devin CLI | graphify devin install |
| Google Antigravity | graphify antigravity install |
Codex users also need multi_agent = true under [features] in ~/.codex/config.toml for parallel extraction. CodeBuddy uses the same Agent tool and PreToolUse hook mechanism as Claude Code. Factory Droid uses the Task tool for parallel subagent dispatch. OpenClaw and Aider use sequential extraction (parallel agent support is still early on those platforms). Trae uses the Agent tool for parallel subagent dispatch and does not support PreToolUse hooks — AGENTS.md is the always-on mechanism.
--platform agents (alias --platform skills) targets the generic cross-framework Agent-Skills locations: the spec's user-global ~/.agents/skills/ (read by npx skills and spec-compliant frameworks) for a global install, and ./.agents/skills/ for a project (--project) install. The bare graphify install stays single-platform (Claude Code) by design — use the named agents platform when you want the skill discoverable by any framework that reads .agents/skills.
Codex uses
$graphifyinstead of/graphify.
Install only what you need:
| Extra | What it adds | Install |
|---|---|---|
pdf |
PDF extraction | uv tool install "graphifyy[pdf] @ git+https://github.com/Vit129/graphify.git" |
office |
.docx and .xlsx support |
uv tool install "graphifyy[office] @ git+https://github.com/Vit129/graphify.git" |
google |
Google Sheets rendering | uv tool install "graphifyy[google] @ git+https://github.com/Vit129/graphify.git" |
video |
Video/audio transcription (faster-whisper + yt-dlp) | uv tool install "graphifyy[video] @ git+https://github.com/Vit129/graphify.git" |
mcp |
MCP stdio server | uv tool install "graphifyy[mcp] @ git+https://github.com/Vit129/graphify.git" |
neo4j |
Neo4j push support | uv tool install "graphifyy[neo4j] @ git+https://github.com/Vit129/graphify.git" |
falkordb |
FalkorDB push support | uv tool install "graphifyy[falkordb] @ git+https://github.com/Vit129/graphify.git" |
svg |
SVG graph export | uv tool install "graphifyy[svg] @ git+https://github.com/Vit129/graphify.git" |
leiden |
Leiden community detection (Python < 3.13 only) | uv tool install "graphifyy[leiden] @ git+https://github.com/Vit129/graphify.git" |
ollama |
Ollama local inference | uv tool install "graphifyy[ollama] @ git+https://github.com/Vit129/graphify.git" |
openai |
OpenAI / OpenAI-compatible APIs | uv tool install "graphifyy[openai] @ git+https://github.com/Vit129/graphify.git" |
gemini |
Google Gemini API | uv tool install "graphifyy[gemini] @ git+https://github.com/Vit129/graphify.git" |
anthropic |
Anthropic Claude API (--backend claude, uses ANTHROPIC_API_KEY) |
uv tool install "graphifyy[anthropic] @ git+https://github.com/Vit129/graphify.git" |
bedrock |
AWS Bedrock (uses IAM, no API key) | uv tool install "graphifyy[bedrock] @ git+https://github.com/Vit129/graphify.git" |
azure |
Azure OpenAI Service (--backend azure, uses AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT) |
uv tool install "graphifyy[openai] @ git+https://github.com/Vit129/graphify.git" |
sql |
SQL schema extraction | uv tool install "graphifyy[sql] @ git+https://github.com/Vit129/graphify.git" |
postgres |
Live PostgreSQL introspection (--postgres DSN) |
uv tool install "graphifyy[postgres] @ git+https://github.com/Vit129/graphify.git" |
dm |
BYOND DreamMaker .dm/.dme AST extraction (may need a C compiler + python3-dev if no wheel matches your platform) |
uv tool install "graphifyy[dm] @ git+https://github.com/Vit129/graphify.git" |
terraform |
Terraform / HCL .tf/.tfvars/.hcl AST extraction |
uv tool install "graphifyy[terraform] @ git+https://github.com/Vit129/graphify.git" |
robot |
Robot Framework .robot/.resource AST extraction |
uv tool install "graphifyy[robot] @ git+https://github.com/Vit129/graphify.git" |
scss |
SCSS .scss AST extraction (plain .css needs no extra) |
uv tool install "graphifyy[scss] @ git+https://github.com/Vit129/graphify.git" |
chinese |
Chinese query segmentation (jieba) | uv tool install "graphifyy[chinese] @ git+https://github.com/Vit129/graphify.git" |
all |
Everything above | uv tool install "graphifyy[all] @ git+https://github.com/Vit129/graphify.git" |
Run this once in your project after building a graph:
| Platform | Command |
|---|---|
| Claude Code | graphify claude install |
| CodeBuddy | graphify codebuddy install |
| Codex | graphify codex install |
| OpenCode | graphify opencode install |
| Kilo Code | graphify kilo install |
| GitHub Copilot CLI | graphify copilot install |
| VS Code Copilot Chat | graphify vscode install |
| Aider | graphify aider install |
| OpenClaw | graphify claw install |
| Factory Droid | graphify droid install |
| Trae | graphify trae install |
| Trae CN | graphify trae-cn install |
| Cursor | graphify cursor install |
| Gemini CLI | graphify gemini install |
| Hermes | graphify hermes install |
| Kimi Code | graphify install --platform kimi |
| Amp | graphify amp install |
| Agent Skills (cross-framework) | graphify agents install (alias graphify skills install) |
| Kiro IDE/CLI | graphify kiro install |
| Pi coding agent | graphify pi install |
| Devin CLI | graphify devin install |
| Google Antigravity | graphify antigravity install |
This writes a small config file that tells your assistant to consult the knowledge graph for codebase questions — preferring scoped queries like graphify query "<question>" over reading the full report or grepping raw files. On platforms that support payload-bearing hooks (Claude Code, Gemini CLI), a hook fires automatically before search-style tool calls (and, on Claude Code, before reading source files one by one via the Read/Glob tools) and nudges your assistant toward the graph path. On the others (Codex, OpenCode, Cursor, etc.), the persistent instruction files (AGENTS.md, .cursor/rules/, etc.) provide the same query-first guidance. GRAPH_REPORT.md is still available for broad architecture review.
CodeBuddy does the same two things as Claude Code: writes a CODEBUDDY.md section telling CodeBuddy to read graphify-out/GRAPH_REPORT.md before answering architecture questions, and installs PreToolUse hooks (.codebuddy/settings.json) that fire before Bash search commands and file reads, nudging toward graphify query instead.
Codex writes to AGENTS.md and also installs a PreToolUse hook in .codex/hooks.json that fires before every Bash tool call — same always-on mechanism as Claude Code.
To remove graphify from all platforms at once: graphify uninstall (add --purge to also delete graphify-out/). Or use the per-platform command (e.g. graphify claude uninstall).
Kilo Code installs the Graphify skill to ~/.config/kilo/skills/graphify/SKILL.md and a native /graphify command to ~/.config/kilo/command/graphify.md. graphify kilo install also writes AGENTS.md plus a native tool.execute.before plugin (.kilo/plugins/graphify.js + .kilo/kilo.json or .kilo/kilo.jsonc registration) so Kilo gets the same always-on graph reminder behavior through native .kilo config.
Cursor writes .cursor/rules/graphify.mdc with alwaysApply: true — Cursor includes it in every conversation automatically, no hook needed.
- God nodes — the most-connected concepts in your project. Everything flows through these.
- Surprising connections — links between things that live in different files or modules. Ranked by how unexpected they are.
- The "why" — inline comments (
# NOTE:,# WHY:,# HACK:), docstrings, and design rationale from docs are extracted as separate nodes linked to the code they explain. - Suggested questions — 4–5 questions the graph is uniquely positioned to answer.
- Confidence tags — every inferred relationship is marked
EXTRACTED,INFERRED, orAMBIGUOUS. You always know what was found vs guessed.
| Type | Extensions |
|---|---|
| Code (54 tree-sitter grammars) | .py .ts .js .jsx .tsx .mjs .gs .go .rs .java .c .cpp .h .hpp .cu .cuh .metal .rb .cs .kt .scala .php .swift .lua .luau .zig .ps1 .psm1 .ex .exs .m .mm .jl .vue .svelte .astro .groovy .gradle .dart .v .sv .svh .sql .f .f90 .f95 .f03 .f08 .pas .pp .dpr .dpk .lpr .inc .dfm .lfm .lpk .sh .bash .fish .json .hook .toml .yaml .yml .css .scss .html .htm .robot .resource .feature .dm .dme .dmi .dmm .dmf .sln .slnx .csproj .fsproj .vbproj .xaml .razor .cshtml (.dm/.dme requires uv tool install "graphifyy[dm] @ git+https://github.com/Vit129/graphify.git"; .scss requires uv tool install "graphifyy[scss] @ git+https://github.com/Vit129/graphify.git"; .robot/.resource requires uv tool install "graphifyy[robot] @ git+https://github.com/Vit129/graphify.git"; CUDA .cu/.cuh and Metal .metal reuse the C++ grammar; .gs reuses the JS grammar; .feature and .fish are hand-written scanners — no published tree-sitter grammar exists for either) |
| Salesforce Apex | .cls .trigger (regex-based; classes, interfaces, enums, methods, triggers, SOQL/DML edges) |
| Terraform / HCL | .tf .tfvars .hcl (requires uv tool install "graphifyy[terraform] @ git+https://github.com/Vit129/graphify.git") |
| MCP configs | .mcp.json mcp.json mcp_servers.json claude_desktop_config.json — extracts server nodes, package refs, env var requirements |
| Package manifests | apm.yml pyproject.toml go.mod pom.xml — one canonical package node per package (by name) plus depends_on edges, so a package referenced from many manifests is a single hub |
| Docs | .md .mdx .qmd .txt .rst (markdown [text](./other.md) links and [[wikilinks]] become references edges between docs) |
| Office | .docx .xlsx (requires uv tool install "graphifyy[office] @ git+https://github.com/Vit129/graphify.git") |
| Google Workspace | .gdoc .gsheet .gslides (opt-in; requires gws auth and --google-workspace; Sheets need uv tool install "graphifyy[google] @ git+https://github.com/Vit129/graphify.git") |
| PDFs | .pdf |
| Images | .png .jpg .webp .gif |
| Video / Audio | .mp4 .mov .mp3 .wav and more (requires uv tool install "graphifyy[video] @ git+https://github.com/Vit129/graphify.git") |
| YouTube / URLs | any video URL (requires uv tool install "graphifyy[video] @ git+https://github.com/Vit129/graphify.git") |
Code is extracted locally with no API calls (AST via tree-sitter). Everything else goes through your AI assistant's model API.
Google Drive for desktop .gdoc, .gsheet, and .gslides files are shortcut
pointers, not document content. To include native Google Docs, Sheets, and Slides
in a headless extraction, install and authenticate the
gws CLI, then run:
uv tool install "graphifyy[google] @ git+https://github.com/Vit129/graphify.git" # needed for Google Sheets table rendering
gws auth login -s drive
graphify extract ./docs --google-workspaceYou can also set GRAPHIFY_GOOGLE_WORKSPACE=1. Graphify exports shortcuts into
graphify-out/converted/ as Markdown sidecars, then extracts those files.
/graphify . # build graph for current folder
/graphify ./docs --update # re-extract only changed files
/graphify . --cluster-only # rerun clustering without re-extracting
/graphify . --cluster-only --resolution 1.5 # more granular communities
/graphify . --cluster-only --exclude-hubs 99 # suppress utility super-hubs from god-node rankings
/graphify . --no-viz # skip the HTML, just the report + JSON
/graphify . --wiki # build a markdown wiki from the graph
graphify export callflow-html # Mermaid architecture/call-flow HTML (auto-regenerates on every git commit if hook is installed)
/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"
/graphify add https://arxiv.org/abs/1706.03762 # fetch a paper and add it
/graphify add <youtube-url> # transcribe and add a video
graphify hook install # auto-rebuild on git commit
graphify merge-graphs a.json b.json # combine two graphs
graphify prs # PR dashboard: CI state, review status, worktree mapping
graphify prs 42 # deep dive on PR #42 with graph impact
graphify prs --triage # AI ranks your review queue (uses whatever backend is configured)
graphify prs --conflicts # PRs sharing graph communities — merge-order riskSee the full command reference below.
If the graph is mainly for your AI assistant to query (rather than for humans to click through graph.html), a good default combination is:
graphify . --no-viz --wiki --exclude-hubs 99--no-viz— skipsgraph.html. Agents never open it; they usegraphify query/path/explainor the wiki. This is usually the largest generated file, so skipping it keeps repeated builds fast andgraphify-out/small.--wiki— builds the agent-crawlable markdown wiki (graphify-out/wiki/). Complements scoped queries with topic-based browsing, and is what the always-on assistant instructions (AGENTS.md,CLAUDE.md, etc.) look for first.--exclude-hubs 99— drops p99-degree utility nodes (base classes, shared config, everything-imports-this files) from the god-node ranking inGRAPH_REPORT.md, so the report highlights real architectural hubs instead of incidental ones.
For large or logic-heavy corpora, add --mode deep (richer relationship extraction, higher API cost) and/or --resolution 1.5 (finer-grained communities for repos spanning several distinct domains).
Once you have a graph, prefer --update over a full re-extract for subsequent runs — it only processes changed files:
if [ -f graphify-out/graph.json ]; then
graphify . --update --no-viz --wiki --exclude-hubs 99
else
graphify . --no-viz --wiki --exclude-hubs 99
fiSave this as scripts/graphify-refresh.sh (or your project's script directory) so the flags don't need to be retyped every run.
Create a .graphifyignore in your project root — same syntax as .gitignore, including ! negation.
.gitignore is respected automatically. graphify reads the .gitignore in each directory. If a .graphifyignore is also present, the two are merged — .graphifyignore patterns are evaluated last, so they win on conflicts (including ! negations). Adding a .graphifyignore only ever excludes more; it never re-includes a file your .gitignore already excluded. Subdirectory scoping works the same way as git — an ignore file only affects its own subtree.
# .graphifyignore
node_modules/
dist/
*.generated.py
# only index src/, ignore everything else
*
!src/
!src/**
graphify-out/ is meant to be committed to git so everyone on the team starts with a map.
Recommended .gitignore additions:
graphify-out/cost.json # local only
# graphify-out/cache/ # optional: commit for speed, skip to keep repo small
manifest.jsonis now portable — keys are stored as relative paths and re-anchored on load, so committing it is safe and avoids a full rebuild on first checkout.
Workflow:
- One person runs
/graphify .and commitsgraphify-out/. - Everyone pulls — their assistant reads the graph immediately.
- Run
graphify hook installto auto-rebuild after each commit (AST only, no API cost). This also sets up a git merge driver sograph.jsonis never left with conflict markers — two devs committing in parallel get their graphs union-merged automatically. - When docs or papers change, run
/graphify --updateto refresh those nodes.
# query the graph from the terminal
graphify query "show the auth flow"
graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json
# expose the graph as an MCP server (for repeated tool-call access)
python -m graphify.serve graphify-out/graph.json
python -m graphify.serve --graph graphify-out/graph.json # --graph flag also accepted
# register with Kimi Code:
kimi mcp add --transport stdio graphify -- python -m graphify.serve graphify-out/graph.json
# or serve over HTTP so a whole team points at one URL (no local graphify needed):
python -m graphify.serve graphify-out/graph.json --transport http --port 8080
python -m graphify.serve graphify-out/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"The MCP server gives your assistant structured access: query_graph, get_node, get_neighbors, shortest_path, list_prs, get_pr_impact, triage_prs.
Queries are scored with real BM25 over camelCase/snake_case-aware tokens, plus a small curated synonym map (login/authenticate, delete/remove, etc.) so a query phrased differently from the code it targets still has a chance to match. A typo (sesion → session) or abbreviation (hus → handleUserSession) that returns nothing on the first pass is automatically corrected against the graph's own vocabulary and re-run, with a note in the response when that happens.
--transport stdio (the default) spawns one local server per developer. --transport http serves the same tools over the MCP Streamable HTTP transport, so a single shared process can serve the graph for the whole team — clients point their IDE MCP config at http://<host>:8080/mcp instead of running graphify locally.
| Flag | Default | Purpose |
|---|---|---|
--transport {stdio,http} |
stdio |
Transport to serve on |
--host |
127.0.0.1 |
HTTP bind host (use 0.0.0.0 to expose beyond localhost) |
--port |
8080 |
HTTP bind port |
--api-key |
env GRAPHIFY_API_KEY |
Require Authorization: Bearer <key> (or X-API-Key) |
--path |
/mcp |
HTTP mount path |
--json-response |
off | Return plain JSON instead of SSE streams |
--stateless |
off | No per-session state (for load-balanced / CI deployments) |
--session-timeout |
3600 |
Reap idle stateful sessions after N seconds (0 disables) |
The default 127.0.0.1 bind is loopback-only. Set --host 0.0.0.0 and --api-key together when exposing on a shared host. Run it in a container:
docker build -t graphify .
docker run -p 8080:8080 -v "$(pwd)/graphify-out:/data" graphify \
/data/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"WSL / Linux note: Ubuntu ships
python3, notpython. Use a venv to avoid conflicts:python3 -m venv .venv && .venv/bin/pip install "graphifyy[mcp] @ git+https://github.com/Vit129/graphify.git"
These are only needed for headless / CI extraction (graphify extract). When running via the /graphify skill inside your IDE, the model API is provided by your IDE session — no extra keys needed.
| Variable | Used for | When required |
|---|---|---|
ANTHROPIC_API_KEY |
Claude (Anthropic) backend | --backend claude |
ANTHROPIC_BASE_URL |
Anthropic-compatible endpoint URL (LiteLLM proxy, gateways, ...) | --backend claude (default: https://api.anthropic.com) |
ANTHROPIC_MODEL |
Model name for the Claude backend — for custom endpoints, use the model name/alias your server exposes | --backend claude (default: claude-sonnet-4-6) |
GEMINI_API_KEY or GOOGLE_API_KEY |
Google Gemini backend | --backend gemini |
OPENAI_API_KEY |
OpenAI or OpenAI-compatible APIs | --backend openai (local servers accept any non-empty value) |
OPENAI_BASE_URL |
OpenAI-compatible server URL (llama.cpp, vLLM, LM Studio, ...) | --backend openai (default: https://api.openai.com/v1) |
OPENAI_MODEL |
Model name for the OpenAI backend — for self-hosted servers, use the model name/alias your server exposes (check its /v1/models endpoint), e.g. LFM2.5-8B-A1B-UD-Q4_K_XL for llama.cpp |
--backend openai (default: gpt-4.1-mini) |
DEEPSEEK_API_KEY |
DeepSeek backend | --backend deepseek |
MOONSHOT_API_KEY |
Kimi Code backend | --backend kimi |
OLLAMA_BASE_URL |
Ollama local inference URL | --backend ollama (default: http://localhost:11434) |
OLLAMA_MODEL |
Ollama model name | --backend ollama (default: auto-detect) |
GRAPHIFY_OLLAMA_NUM_CTX |
Override Ollama KV-cache window size | optional — auto-sized by default |
GRAPHIFY_OLLAMA_KEEP_ALIVE |
Minutes to keep Ollama model loaded | optional — set 0 to unload after each chunk |
AZURE_OPENAI_API_KEY |
Azure OpenAI Service backend | --backend azure |
AZURE_OPENAI_ENDPOINT |
Azure resource endpoint URL | --backend azure (required alongside API key) |
AZURE_OPENAI_API_VERSION |
Azure API version override | optional — default 2024-12-01-preview |
AZURE_OPENAI_DEPLOYMENT or GRAPHIFY_AZURE_MODEL |
Azure deployment name | optional — default gpt-4o |
AWS_* / ~/.aws/credentials |
AWS Bedrock — standard credential chain | --backend bedrock (no API key, uses IAM) |
GRAPHIFY_MAX_WORKERS |
AST parallelism thread count | optional — also --max-workers flag |
GRAPHIFY_MAX_OUTPUT_TOKENS |
Raise output cap for dense corpora | optional — e.g. 32768 for large files |
GRAPHIFY_API_TIMEOUT |
Per-call timeout in seconds for HTTP, claude-cli, and Anthropic SDK backends (default: 600) | optional — also --api-timeout flag |
GRAPHIFY_MAX_RETRIES |
How many times to retry a rate-limited (429) request before giving up (default: 6; honors Retry-After) |
optional — raise for strict per-org limits (e.g. kimi); 0 disables |
GRAPHIFY_FORCE |
Force graph rebuild even with fewer nodes | optional — also --force flag |
GRAPHIFY_GOOGLE_WORKSPACE |
Auto-enable Google Workspace export | optional — set to 1 |
GRAPHIFY_TRIAGE_BACKEND |
Backend for graphify prs --triage |
optional — auto-detected from available keys |
GRAPHIFY_TRIAGE_MODEL |
Model override for triage | optional — e.g. claude-opus-4-7 |
GRAPHIFY_QUERY_LOG |
Override query log path (default: ~/.cache/graphify-queries.log) |
optional — set to empty or /dev/null to silence |
GRAPHIFY_QUERY_LOG_DISABLE |
Set to 1 to disable query logging entirely |
optional |
GRAPHIFY_QUERY_LOG_RESPONSES |
Set to 1 to also log full subgraph responses (off by default) |
optional |
GRAPHIFY_MAX_GRAPH_BYTES |
Override the 512 MiB graph.json size cap — e.g. 700MB, 2GB, or plain bytes |
optional — useful for very large corpora |
GRAPHIFY_LLM_TEMPERATURE |
Override LLM temperature for semantic extraction — e.g. 0.7, or none to omit |
optional — auto-omitted for o1/o3/o4/gpt-5 reasoning models |
- Code files — processed locally via tree-sitter. Nothing leaves your machine. A code-only corpus requires no API key —
graphify extractruns fully offline. - Video / audio — transcribed locally with faster-whisper. Nothing leaves your machine.
- Docs, PDFs, images — sent to your AI assistant for semantic extraction (via the
/graphifyskill, using whatever model your IDE session runs). Headlessgraphify extractrequiresGEMINI_API_KEY/GOOGLE_API_KEY(Gemini),MOONSHOT_API_KEY(Kimi),ANTHROPIC_API_KEY(Claude),OPENAI_API_KEY(OpenAI),DEEPSEEK_API_KEY(DeepSeek), a running Ollama instance (OLLAMA_BASE_URL), AWS credentials via the standard provider chain (Bedrock - no API key needed, uses IAM), or theclaudeCLI binary (Claude Code - no API key needed, uses your Claude subscription). The--dedup-llmflag uses the same key. - Data residency —
graphify extractauto-detects which provider to use based on which API key is set (priority: Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama). For code with data-residency requirements, use--backend ollama(fully local) or pass an explicit--backendflag. Kimi (MOONSHOT_API_KEY) routes to Moonshot AI servers in China. - No telemetry, no usage tracking, no analytics.
- Query logging — every
graphify query,graphify path,graphify explain, and MCPquery_graphcall is logged to~/.cache/graphify-queries.login JSON Lines format (timestamp, question, corpus, nodes returned, duration). Full subgraph responses are not stored by default. SetGRAPHIFY_QUERY_LOG_DISABLE=1to opt out, orGRAPHIFY_QUERY_LOG=/dev/nullto silence without disabling the code path.
graphify: command not found after installing
The CLI is installed but its bin directory isn't on your shell's PATH. Pick the fix for how you installed:
- uv (
uv tool install git+https://github.com/Vit129/graphify.git): the command lands in uv's tool bin dir (~/.local/bin), which a fresh macOS/zsh setup often doesn't have onPATH. Runuv tool update-shell, then open a new terminal. (Find the dir withuv tool dir --bin.) - pipx (
pipx install git+https://github.com/Vit129/graphify.git): runpipx ensurepath, then open a new terminal. - pip (
pip install git+https://github.com/Vit129/graphify.git): pip installs scripts to a user bin dir that may not be onPATH— add~/Library/Python/3.x/bin(macOS) or~/.local/bin(Linux) to yourPATHin~/.zshrc/~/.bashrc, or just runpython -m graphify.
uvx graphify … or uv tool run graphify … fails to resolve graphify
This fork isn't on PyPI, so a bare uvx graphify … looks for a PyPI package called graphify and reports No solution found … no versions of graphify. Point --from at the git repo instead: uvx --from git+https://github.com/Vit129/graphify.git graphify install (same as uv tool run --from git+https://github.com/Vit129/graphify.git graphify install). Or uv tool install git+https://github.com/Vit129/graphify.git once and then call graphify directly.
python -m graphify works but graphify command doesn't
Your shell's PATH doesn't include the bin directory the command was installed to. Prefer uv tool install / pipx install over plain pip, then run uv tool update-shell / pipx ensurepath and open a new terminal (see the install notes above).
/graphify . causes "path not recognized" in PowerShell
PowerShell treats a leading / as a path separator. Use graphify . (no slash) on Windows.
Graph has fewer nodes after --update or rebuild
If a refactor deleted files, the old nodes linger. Pass --force (or set GRAPHIFY_FORCE=1) to overwrite even when the rebuild has fewer nodes.
Graph has duplicate nodes for the same entity (ghost duplicates) Ghost duplicates (same symbol appearing twice — once from AST extraction with a source location, once from semantic extraction without) are now automatically merged at build time. If you see this in a graph built before v0.8.33, run a full re-extract to clean up:
graphify extract . --forceOllama runs out of VRAM / context window exceeded The KV-cache window is auto-sized but may be too large for your GPU. Reduce it:
GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama --token-budget 4000LLM returned invalid JSON / Unterminated string warnings
The model's JSON response hit its output-token limit and was cut off mid-string. graphify auto-recovers (it splits the chunk and re-extracts the halves, and an oversized single document is first sliced at heading/paragraph boundaries so the whole file is still covered), so these warnings are noisy but not data loss. To reduce the churn, raise the output cap or shrink each chunk's output:
GRAPHIFY_MAX_OUTPUT_TOKENS=16384 graphify extract . --mode deep # lift the cap
graphify extract . --mode deep --token-budget 4000 # smaller input chunks -> smaller outputWith a cloud gateway like OpenRouter, prefer --backend openai (set OPENAI_BASE_URL) over the Ollama shim — it's a cleaner OpenAI-compatible path. If the model has its own max-output ceiling, lowering --token-budget is the reliable lever.
Graph HTML is too large to open in a browser (>5000 nodes) Skip HTML generation and use the JSON directly:
graphify cluster-only ./my-project --no-viz
graphify query "..."graph.json has conflict markers after two devs commit at once
Run graphify hook install — it sets up a git merge driver that union-merges graph.json automatically so conflicts never happen.
Extraction returns empty nodes/edges for docs or PDFs Docs, PDFs, and images require an LLM call — code-only corpora need no key. Check that your API key is set and the backend is correct:
ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claudeSkill version mismatch warning in your IDE Your installed graphify version is different from the skill file. Update:
uv tool install --reinstall git+https://github.com/Vit129/graphify.git
graphify install # overwrites the skill file/graphify # run on current directory
/graphify ./raw # run on a specific folder
/graphify ./raw --mode deep # more aggressive relationship extraction
/graphify ./raw --update # re-extract only changed files
/graphify ./raw --directed # preserve edge direction
/graphify ./raw --cluster-only # rerun clustering on existing graph
/graphify ./raw --no-viz # skip HTML visualization
/graphify ./raw --wiki # build agent-crawlable markdown wiki
/graphify ./raw --svg # export graph.svg
/graphify ./raw --graphml # export for Gephi / yEd
/graphify ./raw --neo4j # generate cypher.txt for Neo4j
/graphify ./raw --neo4j-push bolt://localhost:7687
/graphify ./raw --falkordb # generate cypher.txt for FalkorDB
/graphify ./raw --falkordb-push falkordb://localhost:6379
/graphify ./raw --watch # auto-sync as files change
/graphify ./raw --mcp # start MCP stdio server
/graphify add https://arxiv.org/abs/1706.03762
/graphify add <video-url>
/graphify add https://... --author "Name" --contributor "Name"
/graphify query "what connects attention to the optimizer?"
/graphify query "..." --dfs --budget 1500
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"
graphify save-result --question "Q" --answer "A" --nodes Foo Bar --outcome useful # record how a Q&A turned out (work memory; outcome ∈ useful|dead_end|corrected)
graphify reflect # aggregate graphify-out/memory/ outcomes into reflections/LESSONS.md
graphify reflect --if-stale # no-op when LESSONS.md is already newer than every input (cheap to run each session)
graphify reflect --out docs/LESSONS.md # write the lessons doc somewhere else
graphify reflect --graph graphify-out/graph.json # group lessons by community + write the work-memory overlay (.graphify_learning.json)
# the overlay tags nodes preferred/tentative/contested (recency-weighted, with provenance);
# graphify explain / query then show a "Lesson:" hint, flagged "code changed — re-verify" when the source moved on
graphify uninstall # remove from all platforms in one shot
graphify uninstall --purge # also delete graphify-out/
graphify uninstall --project --platform codex # remove project-scoped install files only
graphify hook install # post-commit + post-checkout hooks
graphify hook uninstall
graphify hook status
# always-on assistant instructions - platform-specific
graphify claude install # CLAUDE.md + PreToolUse hook (Claude Code)
graphify claude uninstall
graphify codebuddy install # CODEBUDDY.md + PreToolUse hook (CodeBuddy)
graphify codebuddy uninstall
graphify codex install # AGENTS.md + PreToolUse hook in .codex/hooks.json (Codex)
graphify opencode install # AGENTS.md + tool.execute.before plugin (OpenCode)
graphify kilo install # native Kilo skill + /graphify command + AGENTS.md + .kilo plugin
graphify kilo uninstall
graphify cursor install # .cursor/rules/graphify.mdc (Cursor)
graphify cursor uninstall
graphify gemini install # GEMINI.md + BeforeTool hook (Gemini CLI)
graphify gemini uninstall
graphify copilot install # skill file (GitHub Copilot CLI)
graphify copilot uninstall
graphify aider install # AGENTS.md (Aider)
graphify aider uninstall
graphify claw install # AGENTS.md (OpenClaw)
graphify claw uninstall
graphify droid install # AGENTS.md (Factory Droid)
graphify droid uninstall
graphify trae install # AGENTS.md (Trae)
graphify trae uninstall
graphify trae-cn install # AGENTS.md (Trae CN)
graphify trae-cn uninstall
graphify hermes install # AGENTS.md + ~/.hermes/skills/ (Hermes)
graphify hermes uninstall
graphify amp install # skill file (Amp)
graphify amp uninstall
graphify agents install # ~/.agents/skills/ + AGENTS.md (cross-framework; alias: graphify skills)
graphify agents uninstall
graphify kiro install # .kiro/skills/ + .kiro/steering/graphify.md (Kiro IDE/CLI)
graphify kiro uninstall
graphify pi install # skill file (Pi coding agent)
graphify pi uninstall
graphify devin install # skill file + .windsurf/rules/graphify.md (Devin CLI)
graphify devin uninstall
graphify antigravity install # .agents/rules + .agents/workflows (Google Antigravity)
graphify antigravity uninstall
graphify extract ./docs # headless LLM extraction for CI (no IDE needed)
graphify extract ./docs --backend gemini # explicit backend: gemini, kimi, claude, openai, deepseek, ollama, bedrock, or claude-cli
graphify extract ./docs --backend gemini --model gemini-3.1-pro-preview
graphify extract ./docs --backend ollama # local Ollama (set OLLAMA_BASE_URL / OLLAMA_MODEL) - no API key needed for loopback
OPENAI_BASE_URL=http://localhost:8080/v1 OPENAI_MODEL=my-model graphify extract ./docs --backend openai # any OpenAI-compatible server (llama.cpp, vLLM, LM Studio)
ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_MODEL=my-model graphify extract ./docs --backend claude # any Anthropic-compatible endpoint (LiteLLM proxy, gateways)
GRAPHIFY_OLLAMA_NUM_CTX=32768 graphify extract ./docs --backend ollama # override KV-cache window (auto-sized by default)
GRAPHIFY_OLLAMA_KEEP_ALIVE=0 graphify extract ./docs --backend ollama # unload model after each chunk (saves VRAM on small GPUs)
graphify extract ./docs --backend bedrock # AWS Bedrock via IAM - no API key, uses AWS credential chain
graphify extract ./docs --backend claude-cli # route through Claude Code CLI - no API key, uses your Claude subscription
graphify extract ./docs --backend azure # Azure OpenAI (set AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT)
graphify extract ./docs --max-workers 16 # AST parallelism (also GRAPHIFY_MAX_WORKERS)
graphify extract --postgres "postgresql://user:pass@host/db" # introspect live PostgreSQL schema directly
graphify extract ./my-workspace --cargo # introspect Rust Cargo workspace dependencies directly
graphify extract ./docs --token-budget 30000 # smaller semantic chunks for local/small models
graphify extract ./docs --max-concurrency 2 # fewer parallel LLM calls (useful for local inference)
graphify extract ./docs --api-timeout 900 # longer HTTP timeout for slow local models (default 600s)
graphify extract ./docs --google-workspace # export .gdoc/.gsheet/.gslides via gws before extraction
graphify extract ./docs --mode deep # richer semantic extraction via extended system prompt
graphify extract ./docs --no-cluster # raw extraction only, skip clustering
graphify extract ./docs --timing # print per-stage wall-clock timings to stderr (also works on cluster-only)
graphify extract ./docs --force # overwrite graph.json even if new graph has fewer nodes (use after refactors or to clear ghost duplicates)
graphify extract ./docs --dedup-llm # LLM tiebreaker for ambiguous entity pairs (uses same API key)
graphify extract ./docs --global --as myrepo # extract and register into the cross-project global graph
GRAPHIFY_MAX_OUTPUT_TOKENS=32768 graphify extract ./docs --backend claude # raise output cap for dense corpora
graphify export callflow-html # graphify-out/<project>-callflow.html
graphify export callflow-html --max-sections 8 # cap generated architecture sections
graphify export callflow-html --output docs/arch.html
graphify export callflow-html ./some-repo/graphify-out
graphify global add graphify-out/graph.json --as myrepo # register a project graph into ~/.graphify/global-graph.json
graphify global remove myrepo # remove a project from the global graph
graphify global list # show all registered repos + node/edge counts
graphify global path # print path to the global graph file
graphify prs # PR dashboard: CI, review, worktree, graph impact
graphify prs 42 # deep dive on PR #42
graphify prs --triage # AI triage ranking (auto-detects backend from env)
graphify prs --worktrees # worktree → branch → PR mapping
graphify prs --conflicts # PRs sharing graph communities (merge-order risk)
graphify prs --base main # filter to PRs targeting a specific base branch
graphify prs --repo owner/repo # run against a different GitHub repo
GRAPHIFY_TRIAGE_BACKEND=kimi graphify prs --triage # use a specific backend for triage
graphify clone https://github.com/karpathy/nanoGPT
graphify merge-graphs a.json b.json --out merged.json
graphify --version # print installed version
graphify watch ./src
graphify check-update ./src
graphify update ./src
graphify update ./src --no-cluster # skip reclustering, write raw AST graph only
graphify update ./src --force # overwrite even if new graph has fewer nodes
graphify cluster-only ./my-project
graphify cluster-only ./my-project --graph path/to/graph.json # custom graph location
graphify cluster-only ./my-project --max-concurrency 16 --batch-size 200 # parallel community labeling (large graphs)
graphify cluster-only ./my-project --resolution 1.5 # more, smaller communities
graphify cluster-only ./my-project --exclude-hubs 99 # exclude p99 degree nodes from partitioning
graphify cluster-only ./my-project --no-label # keep "Community N" placeholders
graphify cluster-only ./my-project --backend=gemini # backend for community naming
graphify cluster-only ./my-project --backend=gemini --model gemini-2.5-pro # specific model
graphify label ./my-project # (re)name communities with the configured backend
graphify label ./my-project --backend=openai --model gpt-4o # force a specific backend and model
Community names: inside an agent (Claude Code, Gemini CLI) the agent names communities itself. When you run the bare CLI,
cluster-onlyauto-names them with the configured backend (built-in or custom OpenAI-compatible provider) — pass--no-labelto keepCommunity N, or rungraphify labelto (re)generate names on demand.
- How it works — the extraction pipeline, search/query algorithms (BM25, typo/fuzzy matching, hub-avoiding pathfinding), community detection, confidence scoring, benchmarks
- ARCHITECTURE.md — module breakdown, how to add a language
- Optional integrations — Docker MCP Toolkit + SQLite
Forked from safishamsi/graphify — the original project and its commercial product (Penpax, graphifylabs.ai) are unrelated to this fork.
Contributing
The project uses uv for dev workflow. Install it once, then:
git clone https://github.com/Vit129/graphify.git
cd graphify
# Create the project venv and install graphify + all extras + the dev group
# (pytest). uv installs the dev dependency group by default; pass --no-dev to
# skip it.
uv sync --all-extrasVerify the editable install:
uv run graphify --version
uv run python -c "import graphify; print(graphify.__file__)"Running graphify from an editable git-clone checkout like this also checks
this repo's version.json on main once a day and, on a clean working tree,
asks (y/N) whether to git pull when a newer version is available — never
automatically. Decline and it won't ask again for that version; a dirty tree
gets a notice instead of a prompt. This only applies to editable checkouts
(where graphify/__file__ lives inside a git working tree) — the uv tool install/pipx/pip install paths above are unaffected.
uv run pytest tests/ -q # run the full suite
uv run pytest tests/test_extract.py -q # one module
uv run pytest tests/ -q -k "python" # filter by namemacOS note: the test suite includes both
sample.f90andsample.F90fixtures. These collide on case-insensitive HFS+ / APFS file systems. Run on Linux or in a Docker container if you need to test both Fortran variants simultaneously.
- Active development happens on
main. - Commit style:
fix: <description>/feat: <description>/docs: <description> - Before opening a PR, run
uv run pytest tests/ -qand confirm it passes. - Add a fixture file to
tests/fixtures/and tests totests/test_languages.pyfor any new language extractor.
Worked examples are the most useful contribution. Run /graphify on a real corpus, save the output to worked/{slug}/, write an honest review.md covering what the graph got right and wrong, and open a PR.
Extraction bugs — open an issue with the input file, the cache entry (graphify-out/cache/), and what was missed or wrong.
See ARCHITECTURE.md for module responsibilities and how to add a language.
MIT — see LICENSE.