safishamsi/graphify

당신의 AI 코딩 어시스턴트 (AI coding assistant)에서 /graphify를 입력하세요. 그러면 이 도구가 코드, 문서 (docs), PDF, 이미지, 비디오를 포함한 프로젝트 전체를 매핑하여, 파일을 일일이 검색 (grepping)하는 대신 쿼리 (query)할 수 있는 지식 그래프 (knowledge graph)로 변환해 줍니다.

Claude Code, Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat, Aider, OpenClaw, Factory Droid, Trae, Hermes, Kimi Code, Kiro, Pi, 그리고 Google Antigravity에서 작동합니다.

/graphify .

끝입니다. 세 개의 파일을 얻게 됩니다:

graphify-out/
├── graph.html 모든 브라우저에서 열기 — 노드 클릭, 필터링, 검색 가능
├── GRAPH_REPORT.md 주요 하이라이트: 핵심 개념, 놀라운 연결 고리, 제안된 질문들
...

Mermaid 호출 흐름 다이어그램 (call-flow diagrams)이 포함된 읽기 쉬운 아키텍처 페이지를 원한다면 다음을 실행하세요:

graphify export callflow-html

요구 사항	최소 사양	확인	설치
Python	3.10+	`python --version`	python.org
uv (권장)	제한 없음	`uv --version`	`curl -LsSf https://astral.sh/uv/install.sh
pipx (대안)	제한 없음	`pipx --version`	`pip install pipx`

macOS 빠른 설치 (Homebrew):

brew install python@3.12 uv

Windows 빠른 설치:

winget install astral-sh.uv

Ubuntu/Debian:

sudo apt install python3.12 python3-pip pipx
# 또는 uv 설치:
curl -LsSf https://astral.sh/uv/install.sh | sh

공식 패키지: PyPI 패키지는 graphifyy 입니다 (y가 두 개입니다). PyPI에 있는 다른 graphify* 패키지들은 관련이 없습니다. CLI 명령어는 여전히 graphify 입니다.

1단계 — 패키지 설치:

# 권장 사항 (uv는 graphify를 PATH에 자동으로 추가합니다):
uv tool install graphifyy
# 대안:
...

2단계 — AI 어시스턴트에 스킬 등록:

graphify install

끝입니다. AI 어시스턴트를 열고 /graphify .를 입력하세요.

PowerShell 참고 사항: /graphify . 대신 graphify .를 사용하세요. — PowerShell에서 맨 앞의 슬래시(/)는 경로 구분자(path separator)로 사용됩니다.

graphify: command not found 오류가 발생하나요?
uv tool install graphifyy 또는 pipx install graphifyy를 사용하세요. — 두 방법 모두 CLI를 PATH에 자동으로 추가합니다. 일반 pip를 사용하는 경우, ~/.local/bin (Linux) 또는 ~/Library/Python/3.x/bin (Mac)을 PATH에 추가하거나, python -m graphify로 실행하세요.

플랫폼	설치 명령어
Claude Code (Linux/Mac)	`graphify install`
...

Codex 사용자: ~/.codex/config.toml 파일의 [features] 섹션 아래에 multi_agent = true를 추가하세요. Codex는 /graphify 대신 $graphify를 사용합니다.

필요한 기능만 설치하세요:

추가 기능	추가되는 기능	설치 명령어
`pdf`	PDF 추출	`pip install "graphifyy[pdf]"`
`office`	`.docx` 및 `.xlsx` 지원	`pip install "graphifyy[office]"`
`google`	Google Sheets 렌더링	`pip install "graphifyy[google]"`
`video`	비디오/오디오 전사 (faster-whisper + yt-dlp)	`pip install "graphifyy[video]"`
`mcp`	MCP stdio 서버	`pip install "graphifyy[mcp]"`
`neo4j`	Neo4j 푸시 지원	`pip install "graphifyy[neo4j]"`
`svg`	SVG 그래프 내보내기	`pip install "graphifyy[svg]"`
`leiden`	Leiden 커뮤니티 탐지 (Python < 3.13 전용)	`pip install "graphifyy[leiden]"`
`ollama`	Ollama 로컬 추론	`pip install "graphifyy[ollama]"`
`openai`	OpenAI / OpenAI 호환 API	`pip install "graphifyy[openai]"`
`gemini`	Google Gemini API	`pip install "graphifyy[gemini]"`
`bedrock`	AWS Bedrock (IAM 사용, API 키 불필요)	`pip install "graphifyy[bedrock]"`
`sql`	SQL 스키마 추출	`pip install "graphifyy[sql]"`
`all`	위의 모든 기능	`pip install "graphifyy[all]"`

그래프를 생성한 후 프로젝트에서 다음을 한 번 실행하세요:

플랫폼	명령어
Claude Code	`graphify claude install`
...

이 명령은 어시스턴트에게 코드베이스 관련 질문이 있을 때 전체 보고서를 읽거나 원본 파일을 grep 하는 대신, graphify query "<질문>"과 같은 범위 지정 쿼리(scoped queries)를 사용하여 지식 그래프 (knowledge graph)를 참조하도록 지시하는 작은 설정 파일을 작성합니다. 페이로드(payload)를 전달할 수 있는 훅 (hooks)을 지원하는 플랫폼 (Claude Code, Gemini CLI)에서는 검색 스타일의 도구 호출 (tool calls)이 발생하기 전에 훅이 자동으로 실행되어 어시스턴트가 그래프 경로를 따르도록 유도합니다. 그 외의 플랫폼 (Codex, OpenCode, Cursor 등)에서는 지속성 명령 파일 (AGENTS.md, .cursor/rules/ 등)이 동일한 쿼리 우선 가이드를 제공합니다. 광범위한 아키텍처 검토를 위해서는 GRAPH_REPORT.md를 여전히 사용할 수 있습니다.

모든 플랫폼에서 graphify를 한 번에 제거하려면: graphify uninstall (graphify-out/ 디렉토리까지 삭제하려면 --purge를 추가하세요). 또는 플랫폼별 명령어를 사용할 수 있습니다 (예: graphify claude uninstall).

God nodes— 프로젝트에서 가장 연결성이 높은 개념들입니다. 모든 흐름이 이 노드들을 통과합니다.
Surprising connections— 서로 다른 파일이나 모듈에 존재하는 요소들 사이의 연결입니다. 얼마나 예상치 못한지에 따라 순위가 매겨집니다.
The "why"— 인라인 주석 (# NOTE:, # WHY:, # HACK:), 독스트링 (docstrings), 그리고 문서의 설계 근거 (design rationale)가 추출되어, 설명하는 코드와 연결된 별도의 노드로 생성됩니다.
Suggested questions— 그래프가 독보적으로 답변할 수 있는 위치에 있는 4~5개의 질문입니다.
Confidence tags— 모든 추론된 관계는 EXTRACTED, INFERRED, 또는 AMBIGUOUS로 표시됩니다. 무엇이 발견된 것이고 무엇이 추측된 것인지 항상 알 수 있습니다.

유형	확장자
코드 (31개 언어)	`.py .ts .js .jsx .tsx .mjs .go .rs .java .c .cpp .h .hpp .rb .cs .kt .scala .php .swift .lua .luau .zig .ps1 .ex .exs .m .mm .jl .vue .svelte .astro .groovy .gradle .dart .v .sv .sql .f .f90 .f95 .f03 .f08 .pas .pp .dpr .dpk .lpr .inc .dfm .lfm .lpk .sh .bash .json`
...

코드는 API 호출 없이 로컬에서 추출됩니다 (tree-sitter를 통한 AST 활용). 그 외의 모든 작업은 귀하의 AI 어시스턴트 모델 API를 통해 진행됩니다.

데스크톱용 Google Drive의 .gdoc, .gsheet, .gslides 파일은 문서 내용이 아닌 바로가기 포인터(shortcut pointers)입니다. 헤드리스 추출(headless extraction) 과정에 네이티브 Google Docs, Sheets, Slides를 포함하려면 gws CLI를 설치 및 인증한 후 다음을 실행하십시오:

pip install "graphifyy[google]" # Google Sheets 테이블 렌더링에 필요
gws auth login -s drive
graphify extract ./docs --google-workspace

또한 GRAPHIFY_GOOGLE_WORKSPACE=1을 설정할 수도 있습니다. Graphify는 바로가기 파일들을 graphify-out/converted/ 경로에 Markdown 사이드카(sidecars) 파일로 내보낸 다음, 해당 파일들을 추출합니다.

/graphify . # 현재 폴더에 대한 그래프 구축
/graphify ./docs --update # 변경된 파일만 재추출
/graphify . --cluster-only # 재추출 없이 클러스터링(clustering)만 다시 실행
...

전체 명령어 참조는 아래를 확인하십시오.

프로젝트 루트에 .graphifyignore 파일을 생성하십시오. ! 부정(negation)을 포함하여 .gitignore와 동일한 구문을 사용합니다:

# .graphifyignore
node_modules/
dist/
...

graphify-out/은 팀원 모두가 지도로 시작할 수 있도록 git에 커밋하는 것을 권장합니다.

권장되는 .gitignore 추가 사항:

graphify-out/manifest.json # 수정 시간(mtime) 기반이므로 git clone 후 깨질 수 있음
graphify-out/cost.json # 로컬 전용
# graphify-out/cache/ # 선택 사항: 속도를 위해 커밋하거나, 저장소 크기를 작게 유지하기 위해 제외

워크플로우(Workflow):

한 사람이 /graphify .를 실행하고 graphify-out/을 커밋합니다. - 모든 팀원이 pull을 받으면, 각자의 어시스턴트가 즉시 그래프를 읽을 수 있습니다.
graphify hook install을 실행하면 각 커밋 후에 자동으로 재구축됩니다 (AST만 사용하므로 API 비용이 발생하지 않음). 이는 또한 git 머지 드라이버(merge driver)를 설정하여 graph.json에 충돌 표시(conflict markers)가 남지 않도록 합니다. 즉, 두 개발자가 병렬로 커밋하더라도 그래프가 자동으로 합집합 머지(union-merged)됩니다. - 문서나 논문이 변경되면 /graphify --update를 실행하여 해당 노드(nodes)를 갱신하십시오.

# 터미널에서 그래프 쿼리(query)
graphify query "show the auth flow"
graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json
...

MCP 서버는 어시스턴트에게 구조화된 접근 권한을 제공합니다: query_graph, get_node

, get_neighbors

, shortest_path

, list_prs

, get_pr_impact

, triage_prs.

WSL / Linux 참고 사항: Ubuntu에는 python이 아닌 python3가 포함되어 있습니다. 충돌을 방지하려면 가상 환경 (venv)을 사용하세요: python3 -m venv .venv && .venv/bin/pip install "graphify[mcp]"

이것들은 오직 헤드리스 / CI 추출 (headless / CI extraction) (graphify extract) 시에만 필요합니다. IDE 내부에서 /graphify 스킬을 통해 실행할 때는 모델 API가 IDE 세션에 의해 제공되므로 별도의 키가 필요하지 않습니다.

변수 (Variable)	용도	필요 시점
`ANTHROPIC_API_KEY`	Claude (Anthropic) 백엔드	`--backend claude`
`GEMINI_API_KEY` 또는 `GOOGLE_API_KEY`	Google Gemini 백엔드	`--backend gemini`
`OPENAI_API_KEY`	OpenAI 또는 OpenAI 호환 API	`--backend openai`
`DEEPSEEK_API_KEY`	DeepSeek 백엔드	`--backend deepseek`
`MOONSHOT_API_KEY`	Kimi Code 백엔드	`--backend kimi`
`OLLAMA_BASE_URL`	Ollama 로컬 추론 (inference) URL	`--backend ollama` (기본값: `http://localhost:11434`)
`OLLAMA_MODEL`	Ollama 모델 이름	`--backend ollama` (기본값: 자동 감지)
`GRAPHIFY_OLLAMA_NUM_CTX`	Ollama KV-캐시 (KV-cache) 윈도우 크기 재정의	선택 사항 — 기본적으로 자동 크기 조절
`GRAPHIFY_OLLAMA_KEEP_ALIVE`	Ollama 모델을 로드된 상태로 유지할 시간 (분)	선택 사항 — 각 청크(chunk) 후에 언로드하려면 `0`으로 설정
`AWS_*` / `~/.aws/credentials`	AWS Bedrock — 표준 자격 증명 체인 (credential chain)	`--backend bedrock` (API 키 없이 IAM 사용)
`GRAPHIFY_MAX_WORKERS`	AST 병렬 처리 스레드 수	선택 사항 — `--max-workers` 플래그와 동일
`GRAPHIFY_MAX_OUTPUT_TOKENS`	밀집 코퍼스 (dense corpora)를 위한 출력 제한 상향	선택 사항 — 예:

코드 파일— tree-sitter를 통해 로컬에서 처리됩니다. 어떤 데이터도 사용자의 기기를 떠나지 않습니다. 비디오 / 오디오— faster-whisper를 통해 로컬에서 전사 (transcribed)됩니다. 어떤 데이터도 사용자의 기기를 떠나지 않습니다. 문서, PDF, 이미지— 의미론적 추출 (semantic extraction)을 위해 AI 어시스턴트에게 전송됩니다 (IDE 세션이 실행 중인 모델을 사용하는 /graphify 스킬을 통해). 헤드리스(Headless) graphify extract를 실행하려면 다음 중 하나가 필요합니다: GEMINI_API_KEY (Gemini), MOONSHOT_API_KEY (Kimi), ANTHROPIC_API_KEY (Claude), OPENAI_API_KEY (OpenAI), DEEPSEEK_API_KEY (DeepSeek), 실행 중인 Ollama 인스턴스 (OLLAMA_BASE_URL), 표준 프로바이더 체인을 통한 AWS 자격 증명 (Bedrock - API 키 불필요, IAM 사용), 또는 claude CLI 바이너리 (Claude Code - API 키 불필요, 사용자의 Claude 구독 사용). --dedup-llm 플래그는 동일한 키를 사용합니다. - 텔레메트리 (telemetry), 사용 추적, 분석 데이터 수집이 없습니다.

pip install graphifyy 후 graphify: command not found 오류
pip는 스크립트를 사용자의 bin 디렉토리에 설치하지만, 해당 디렉토리가 PATH에 포함되어 있지 않을 수 있습니다. 해결 방법:

macOS: ~/.zshrc의 PATH에 ~/Library/Python/3.x/bin 추가
Linux: ~/.bashrc의 PATH에 ~/.local/bin 추가
또는 uv tool install graphifyy / pipx install graphifyy 사용 — 두 방식 모두 PATH를 자동으로 관리합니다.

python -m graphify는 작동하지만 graphify 명령어가 작동하지 않는 경우
셸의 PATH에 Python 스크립트 디렉토리가 포함되어 있지 않습니다. 일반 pip 대신 uv 또는 pipx를 사용하세요.

PowerShell에서 /graphify . 실행 시 "path not recognized" 오류 발생
PowerShell은 맨 앞의 /를...

경로 구분자 (path separator)로 인식합니다. Windows에서는 슬래시를 사용하지 말고 graphify .를 사용하세요.--update 또는 rebuild 후 그래프의 노드 수가 줄어드는 경우
리팩터링(refactor)으로 인해 파일이 삭제된 경우, 이전 노드들이 남아 있을 수 있습니다. 재빌드(rebuild) 시 노드 수가 줄어들더라도 덮어쓰려면 --force를 전달하거나 (또는 GRAPHIFY_FORCE=1` 설정) 사용하세요.동일한 엔티티에 대해 그래프에 중복된 노드가 존재하는 경우 (유령 중복, ghost duplicates)
이는 시맨틱(semantic) 추출과 AST (Abstract Syntax Tree) 추출 방식이 노드 ID 형식에 대해 서로 일치하지 않을 때 발생합니다. 정리를 위해 전체 재추출(re-extract)을 실행하세요:

graphify extract . --force

Ollama의 VRAM 부족 또는 컨텍스트 윈도우 (context window) 초과
KV-캐시 (KV-cache) 윈도우는 자동으로 크기가 조정되지만, 사용 중인 GPU에 비해 너무 클 수 있습니다. 크기를 줄이세요:

GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama --token-budget 4000

Graph HTML 파일이 너무 커서 브라우저에서 열 수 없는 경우 (>5000개 노드)
HTML 생성을 건너뛰고 JSON을 직접 사용하세요:

graphify cluster-only ./my-project --no-viz
graphify query "..."

두 명의 개발자가 동시에 커밋하여 graph.json에 충돌 마커 (conflict markers)가 발생한 경우
다음 명령어를 실행하세요:

graphify hook install

— 이 명령은 graph.json을 유니온 머지 (union-merge)하는 git 머지 드라이버 (git merge driver)를 설정합니다.

safishamsi/graphify

요약

핵심 포인트

댓글