safishamsi/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...

74k stars · 7.4k forks · 248 watchers · Python Topics: tree-sitter, skills, gemini, knowledge-graph, leiden, codex, rag, graphrag, antigravity, claude-code, openclaw

README

🇺🇸 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. 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-html

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

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

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. 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. 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 .js .jsx .tsx .mjs .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 .json .dm .dme .dmi .dmm .dmf .sln .slnx .csproj .fsproj .vbproj .xaml .razor .cshtml (.dm/.dme requires uv tool install graphifyy[dm]; 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 small

manifest.json is 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 commits graphify-out/. Everyone pulls — their assistant reads the graph immediately. Run graphify hook install to auto-rebuild after each commit (AST only, no API cost). This also sets up a git merge driver so graph.json is never left with conflict markers — two devs committing in parallel get their graphs union-merged automatically. When docs or papers change, run /graphify --update to refresh those nodes.

Using the graph directly

query the graph from the terminal

expose the graph as an MCP server (for repeated tool-call access)

register with Kimi Code:

or serve over HTTP so a whole team points at one URL (no local graphify needed):

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, not python. Use a venv to avoid conflicts: python3 -m venv .venv && .venv/bin/pip install "graphifyy[mcp]"

Environment variables 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)

ANTHROPI

source