graphify

Graphify는 codebase, 문서, database schema 등을 query 가능한 knowledge graph로 변환하는 open-source CLI 및 AI coding assistant skill이다. 공식 PyPI package 이름은 graphifyy(y 두 개)이고 설치 후 실행하는 command는 graphify다.

• source code의 symbol과 관계를 graph로 만들고 query, path, explain으로 탐색한다.
• 기본 결과는 graphify-out/graph.html, graphify-out/GRAPH_REPORT.md, graphify-out/graph.json에 저장된다.
• Claude Code, Codex, Gemini CLI, Cursor 등에는 assistant skill로 등록할 수 있으며 graph를 MCP server로 제공할 수도 있다.
• Python 3.10 이상이 필요하고 공식 문서는 격리 설치되는 uv tool install을 권장한다.

공식 upstream 문서는 Python 3.10 이상과 uv 또는 pipx를 사용한다. distribution repository의 Python version이 요구 조건을 만족하는지 먼저 확인한다.

# upstream이 안내하는 uv installer
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Graphify 설치
uv tool install graphifyy

Graphify 전용 공식 RPM/DNF repository는 안내되지 않는다. Linux 공통 uv 설치 후 PyPI package를 격리 설치한다.

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install graphifyy

brew install python@3.12 uv
uv tool install graphifyy

winget install astral-sh.uv
uv tool install graphifyy

# 대안
pipx install graphifyy
 
# 설치 확인
graphify --version
 
# update
uv tool upgrade graphifyy

• uv tool install 후 command를 찾지 못하면 uv tool update-shell을 실행하고 terminal을 다시 연다.
• pipx를 사용했다면 pipx ensurepath를 실행하고 terminal을 다시 연다.
• 일회성 실행이 필요하면 package와 command 이름을 분리한 uvx –from graphifyy graphify … 형식을 사용한다. uvx graphify …는 package 이름이 달라 resolve되지 않는다.

# 현재 repository 분석
graphify .
 
# 변경된 파일 중심으로 갱신
graphify update .
 
# graph query
graphify query "auth와 database는 어떻게 연결되는가?"
graphify path "UserService" "DatabasePool"
graphify explain "RateLimiter"

• graphify [OPTIONS] PATH: 대상 directory를 분석해 graph 생성
• graphify update [OPTIONS] PATH: 기존 graph 갱신
• graphify query QUESTION: 자연어 또는 keyword로 관련 node와 edge 탐색
• graphify path SOURCE TARGET: 두 concept 사이의 경로 탐색
• graphify explain CONCEPT: node의 위치와 관계 설명
• graphify export callflow-html: Mermaid 기반 architecture/call-flow HTML 생성
• graphify prs [OPTIONS]: PR 상태와 graph 영향 분석

graphify .
graphify ./docs --update
graphify . --mode deep
graphify . --no-viz
graphify . --wiki
graphify . --cluster-only --resolution 1.5

• –mode deep: 여러 pass를 사용하는 더 깊은 관계 추출
• –update: 변경된 file 중심으로 재추출
• –no-viz: interactive HTML 생성을 생략
• –wiki: graph에서 Markdown wiki 생성
• –cluster-only: 추출을 다시 하지 않고 기존 graph의 clustering 재실행

graphify query "billing을 소유하는 component는?"
graphify path "ApiGateway" "RedisClient"
graphify explain "AuthService"
graphify merge-graphs a.json b.json --out merged.json

관계의 confidence는 EXTRACTED, INFERRED, AMBIGUOUS로 구분된다. 중요한 판단에는 결과의 source file과 line citation을 함께 검토한다.

# 감지된 assistant에 skill 등록
graphify install
 
# 현재 project에만 등록
graphify install --project
 
# Codex project-scoped 등록
graphify install --project --platform codex
 
# 제거; --purge를 추가하면 graphify-out도 삭제
graphify uninstall

• Claude Code 등 slash-command 기반 assistant에서는 /graphify .를 사용한다.
• Codex에서는 $graphify skill 이름을 사용한다.
• PowerShell에서는 leading slash가 path separator로 처리되므로 terminal에서 graphify .를 사용한다.
• project-scoped install은 .agents/skills/graphify/, .claude/skills/graphify/ 등 platform별 경로를 만들 수 있다. commit 전에 생성 파일을 검토한다.

# stdio server
python -m graphify.serve graphify-out/graph.json
 
# 여러 client가 공유하는 HTTP server
python -m graphify.serve graphify-out/graph.json --transport http --port 8080
 
# console script
graphify-mcp graphify-out/graph.json

MCP server는 query, node 조회, neighbor 탐색, shortest path, graph 통계, PR 영향 분석 tool을 제공한다. HTTP transport를 외부에 노출할 때는 –api-key 또는 GRAPHIFY_API_KEY를 설정하고 network 접근을 제한한다.

• output directory: graphify-out/
• ignore file: .graphifyignore; .gitignore도 자동으로 반영된다.
• local inference: –backend ollama, OLLAMA_BASE_URL, OLLAMA_MODEL
• cloud backend: –backend claude|gemini|openai|azure|bedrock와 provider별 environment variable
• query log: 기본 비활성. GRAPHIFY_QUERY_LOG_ENABLE=1 또는 GRAPHIFY_QUERY_LOG로 명시적으로 활성화한다.

# .graphifyignore
.env
secrets/
vendor/
generated/
graphify-out/

필요한 기능만 extra로 설치한다.

uv tool install "graphifyy[pdf]"
uv tool install "graphifyy[office]"
uv tool install "graphifyy[mcp]"
uv tool install "graphifyy[svg]"
uv tool install "graphifyy[sql]"
uv tool install "graphifyy[terraform]"
uv tool install "graphifyy[all]"

• graphify: command not found: uv tool update-shell 또는 pipx ensurepath 실행 후 terminal을 다시 연다.
• uvx graphify가 package를 찾지 못함: uvx –from graphifyy graphify …로 package 이름을 명시한다.
• update 후 assistant skill version mismatch: uv tool upgrade graphifyy 다음 graphify install을 다시 실행한다.
• docs/PDF graph가 비어 있음: 필요한 extra와 AI backend credential을 확인한다. secret을 command line에 직접 기록하지 않는다.
• refactor 후 삭제된 node가 남거나 graph 크기 보호가 update를 막으면 source와 backup을 확인한 뒤 –force 사용 여부를 판단한다.

• Python 3.10 이상이 필요하다.
• leiden extra는 공식 문서 기준 Python 3.13 미만에서 지원된다.
• graph source와 CLI/skill version이 다르면 query 결과가 달라질 수 있으므로 team에서는 version과 graphify-out/ commit 정책을 합의한다.

graphify --help

이 환경에는 graphify가 기본 설치되어 있지 않아 live help를 실행하지 않았다.
현재 command와 option은 공식 Graphify documentation을 참고한다.

• Codex CLI
• Claude Code
• Gemini CLI
• uv
• Graphify official documentation
• Graphify GitHub repository

• codex:: 2026-07-20 Added Graphify installation, graph build/query, assistant skill, MCP, configuration, security, and troubleshooting guidance.