Graphify-Labs/graphify

AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs, papers, images, or videos into a querya...

85.3k stars · 8.4k forks · Python Topics: tree-sitter, skills, gemini, knowledge-graph, leiden, codex, rag, graphrag, antigravity, claude-code, openclaw

README

Read this in other languages 🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇮🇳 हिन्दी | 🇧🇷 Português | 🇷🇺 Русский | 🇸🇦 العربية | 🇮🇷 فارسی | 🇮🇹 Italiano | 🇵🇱 Polski | 🇳🇱 Nederlands | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇻🇳 Tiếng Việt | 🇮🇩 Bahasa Indonesia | 🇸🇪 Svenska | 🇬🇷 Ελληνικά | 🇷🇴 Română | 🇨🇿 Čeština | 🇫🇮 Suomi | 🇩🇰 Dansk | 🇳🇴 Norsk | 🇭🇺 Magyar | 🇹🇭 ภาษาไทย | 🇺🇿 Oʻzbekcha | 🇹🇼 繁體中文 | 🇵🇭 Filipino | 🇮🇱 עברית

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.

Code maps for free, fully local. Code is parsed with tree-sitter AST: deterministic, no LLM, nothing leaves your machine. (Docs, PDFs, images and video use your assistant's model, or a configured API key, for a semantic pass.) Every edge is explained. Each connection is tagged EXTRACTED (explicit in the source) or INFERRED (resolved by graphify), so you can tell what was read directly from what was inferred. Not a vector index. No embeddings, no vector store: a real graph you traverse. Ask a question, trace the path between two things, or explain one concept.

The FastAPI codebase mapped by graphify. Every node is a concept, colors are detected communities, and the whole thing is clickable in graph.html.

Get started (30 seconds): uv tool install graphifyy # install the CLI (or: pipx install graphifyy) graphify install # register the skill with your AI assistant Then, in your AI assistant: /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

Works in Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and 15+ more — pick your platform.

See it in action

Once the graph is built you query it instead of reading files. Real output, graphify run on the FastAPI codebase shown above: $ graphify explain "APIRouter" Node: APIRouter Source: routing.py L2210 Community: 2 Degree: 47

Connections (47): --> RequestValidationError [uses] [INFERRED] --> Dependant [uses] [INFERRED] --> .get() [method] [EXTRACTED] <-- _init_.py [imports] [EXTRACTED] ...

$ graphify path "FastAPI" "ModelField" Shortest path (3 hops): FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

Every edge carries a confidence tag (EXTRACTED = explicit in the source, INFERRED = derived by resolution), so you can tell what was read directly from what was inferred. graphify query "<question>" returns a scoped subgraph for a plain-language question, and graphify path A B traces how any two things connect.

What it does What you get out of the box:

Capability What you get

God nodes The most-connected concepts, so you see what everything flows through

Communities The graph split into subsystems (Leiden), with LLM-free labels

Cross-file links calls / imports / inherits / mixes_in resolved across ~40 languages via tree-sitter AST

Query, path, explain Ask a question, trace the path between two things, or explain one concept, all against graph.json

Rationale + doc refs

NOTE: / # WHY: comments and ADR/RFC citations become first-class nodes linked to the code

Beyond code Docs, PDFs, images, and video/audio all map into the same graph

Local-first Code is parsed locally with tree-sitter (no LLM, nothing leaves your machine); only the semantic pass over docs/media calls a backend, and only if you configure one

Benchmarks

Benchmark Metric graphify Field

LOCOMO (n=300) recall@10 0.497 mem0 0.048, supermemory 0.149

LOCOMO (n=300) QA accuracy 45.3% supermemory 49.7%, mem0 27.3%

LongMemEval-S (n=50) QA accuracy 76% tied with dense RAG

Graph build LLM credits 0 per-token for most systems

Every system ran on the same harness with the same model and budgets, scored by a judge blind-validated against a second judge (90.6% agreement, Cohen's kappa 0.81). Full per-system tables, the code-intelligence result, and reproduction commands: BENCHMARKS.md.

Prerequisites

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 uv Windows quick install: winget install astral-sh.uv Ubuntu/Debian: sudo apt install python3.12 python3-pip pipx

or install uv:

Install

Official package: The PyPI package is graphifyy (double-y). Other graphify* packages on PyPI are not affiliated. The CLI command is still graphify.

Step 1 — install the package:

Recommended (isolated env; if 'graphify' isn't found after, run: uv tool update-shell):

Alternatives:

PowerShell note: Use graphify . not /graphify . — the leading slash is a path separator in PowerShell.

graphify: command not found? uv tool install / pipx install put the graphify command 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 your PATH yet: run uv tool update-shell (or pipx ensurepath), then open a new terminal. With plain pip, add ~/.local/bin (Linux) or ~/Library/Python/3.x/bin (Mac) to your PATH, or run python -m graphify.

Running with uvx / uv tool run instead of installing? Name the package, not the command: uvx --from graphifyy graphify install. Plain uvx graphify … fails (No solution found … no versions of graphify) because uv tool run reads the first word as a package, and the package is graphifyy — the graphify command lives inside it.

Avoid pip install on Mac/Windows if possible. The skill resolves Python at runtime from graphify-out/.graphify_python; if that points to a different environment than where pip installed the package, you'll get ModuleNotFoundError: No module named 'graphify'. uv tool install and pipx install isolate the package in their own env and avoid this entirely.

Git hooks and uv tool / pipx: graphify hook install embeds 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/bin is not on PATH. If you reinstall or upgrade graphify, re-run graphify hook install to refresh the embedded path.

Pick your platform (20+ assistants, click to expand)

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, so 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 $graphify instead of /graphify.

Optional extras (install only what you need)

Extra What it adds Install

pdf PDF extraction uv tool install "graphifyy[pdf]"

office .docx and .xlsx support uv tool install "graphifyy[office]"

google Google Sheets rendering uv tool install "graphifyy[google]"

video Video/audio transcription (faster-whisper + yt-dlp) uv tool install "graphifyy[video]"

mcp MCP stdio server uv tool install "graphifyy[mcp]"

neo4j Neo4j push support uv tool install "graphifyy[neo4j]"

falkordb FalkorDB push support uv tool install "graphifyy[falkordb]"

svg SVG graph export uv tool install "graphifyy[svg]"

leiden Leiden community detection (Python < 3.13 only) uv tool install "graphifyy[leiden]"

ollama Ollama local inference uv tool install "graphifyy[ollama]"

openai OpenAI / OpenAI-compatible APIs uv tool install "graphifyy[openai]"

gemini Google Gemini API uv tool install "graphifyy[gemini]"

anthropic Anthropic Claude API (--backend claude, uses ANTHROPIC_API_KEY) uv tool install "graphifyy[anthropic]"

bedrock AWS Bedrock (uses IAM, no API key) uv tool install "graphifyy[bedrock]"

azure Azure OpenAI Service (--backend azure, uses AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT) uv tool install "graphifyy[openai]"

sql SQL schema extraction uv tool install "graphifyy[sql]"

postgres Live PostgreSQL introspection (--postgres DSN) uv tool install "graphifyy[postgres]"

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]"

terraform Terraform / HCL .tf/.tfvars/.hcl AST extraction uv tool install "graphifyy[terraform]"

pascal Pascal / Delphi .pas/.dpr/.dpk/.inc AST extraction (more accurate calls/inherits edges; falls back to a regex extractor when absent) uv tool install "graphifyy[pascal]"

chinese Chinese query segmentation (jieba) uv tool install "graphifyy[chinese]"

all Everything above uv tool install "graphifyy[all]"

Make your assistant always use the graph 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.

Hook platforms (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. Instruction-file platforms (Codex, OpenCode, Cursor, etc.): 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. 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, so Cursor includes it in every conversation automatically, no hook needed. 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).

What's in the report

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, or AMBIGUOUS. You always know what was found vs guessed.

What files it handles

Type Extensions

Code (36 tree-sitter grammars) .py .ts .mts .cts .js .jsx .tsx .mjs .go .rs .java .c .cpp .cc .cxx .h .hpp .cu .cuh .metal .rb .cs .kt .kts .scala .php .swift .lua .luau .toc .zig .ps1 .psm1 .psd1 .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 .json .dm .dme .dmi .dmm .dmf .sln .slnx .csproj .fsproj .vbproj .xaml .razor .cshtml (.dm/.dme requires uv tool install graphifyy[dm]; .mts/.cts reuse the TypeScript grammar, .cc/.cxx and CUDA .cu/.cuh and Metal .metal reuse the C++ grammar)

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])

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 .html .txt .rst .yaml .yml (markdown text links and [[wikilinks]] become references edges between docs)

Office .docx .xlsx (requires uv tool install graphifyy[office])

Google Workspace .gdoc .gsheet .gslides (opt-in; requires gws auth and --google-workspace; Sheets need uv tool install graphifyy[google])

PDFs .pdf

Images .png .jpg .webp .gif

Video / Audio .mp4 .mov .mp3 .wav and more (requires uv tool install graphifyy[video])

YouTube / URLs any video URL (requires uv tool install graphifyy[video])

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]" # needed for Google Sheets table rendering gws auth login -s drive graphify extract ./docs --google-workspace You can also set GRAPHIFY_GOOGLE_WORKSPACE=1. Graphify exports shortcuts into graphify-out/converted/ as Markdown sidecars, then extracts those files.

Common commands /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 risk See the full command reference below.

Ignoring files 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

only index src/, ignore everything else

Team setup 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 smal

source