graphify

KO | EN

gitlite — search

#hacktoberfest #typescript #golang #machine-learning #deep-learning #docker #windows #awesome #cli #vue #security #ios #openai #open-source

(★ 107,046)

문서, SQL 스키마, 설정 파일, PDF 등 모든 코드베이스를 쿼리 가능한 지식 그래프로 변환하세요. Claude Code, Cursor, Codex, Gemini CLI를 위한 /graphify 스킬: 로컬 결정론적 AST 파싱, 모든 에지 설명 제공, 벡터 저장소 불필요.

graphify 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

🇺🇸 <a href="README.md">English</a> | 🇨🇳 <a href="docs/translations/README.zh-CN.md">简体中文</a> | 🇯🇵 <a href="docs/translations/README.ja-JP.md">日本語</a> | 🇰🇷 <a href="docs/translations/README.ko-KR.md">한국어</a> | 🇩🇪 <a href="docs/translations/README.de-DE.md">Deutsch</a> | 🇫🇷 <a href="docs/translations/README.fr-FR.md">Français</a> | 🇪🇸 <a href="docs/translations/README.es-ES.md">Español</a> | 🇮🇳 <a href="docs/translations/README.hi-IN.md">हिन्दी</a> | 🇧🇷 <a href="docs/translations/README.pt-BR.md">Português</a> | 🇷🇺 <a href="docs/translations/README.ru-RU.md">Русский</a> | 🇸🇦 <a href="docs/translations/README.ar-SA.md">العربية</a> | 🇮🇷 <a href="docs/translations/README.fa-IR.md">فارسی</a> | 🇮🇹 <a href="docs/translations/README.it-IT.md">Italiano</a> | 🇵🇱 <a href="docs/translations/README.pl-PL.md">Polski</a> | 🇳🇱 <a href="docs/translations/README.nl-NL.md">Nederlands</a> | 🇹🇷 <a href="docs/translations/README.tr-TR.md">Türkçe</a> | 🇺🇦 <a href="docs/translations/README.uk-UA.md">Українська</a> | 🇻🇳 <a href="docs/translations/README.vi-VN.md">Tiếng Việt</a> | 🇮🇩 <a href="docs/translations/README.id-ID.md">Bahasa Indonesia</a> | 🇸🇪 <a href="docs/translations/README.sv-SE.md">Svenska</a> | 🇬🇷 <a href="docs/translations/README.el-GR.md">Ελληνικά</a> | 🇷🇴 <a href="docs/translations/README.ro-RO.md">Română</a> | 🇨🇿 <a href="docs/translations/README.cs-CZ.md">Čeština</a> | 🇫🇮 <a href="docs/translations/README.fi-FI.md">Suomi</a> | 🇩🇰 <a href="docs/translations/README.da-DK.md">Dansk</a> | 🇳🇴 <a href="docs/translations/README.no-NO.md">Norsk</a> | 🇭🇺 <a href="docs/translations/README.hu-HU.md">Magyar</a> | 🇹🇭 <a href="docs/translations/README.th-TH.md">ภาษาไทย</a> | 🇺🇿 <a href="docs/translations/README.uz-UZ.md">Oʻzbekcha</a> | 🇹🇼 <a href="docs/translations/README.zh-TW.md">繁體中文</a> | 🇵🇭 <a href="docs/translations/README.fil-PH.md">Filipino</a> | 🇮🇱 <a href="docs/translations/README.he-IL.md">עברית</a>

</details>
</div>

공개 v1 출시 전 graphify 플랫폼 얼리 액세스가 오픈되었습니다: <a href="https://app.graphify.com/login">app.graphify.com</a>

AI 코딩 어시스턴트에서 `/graphify`를 입력하면 전체 프로젝트(코드, 문서, PDF, 이미지, 동영상)가 **지식 그래프(knowledge graph)**로 매핑됩니다. 이 그래프를 통해 파일 전체를 **grep하는 대신 직접 질의(query)**할 수 있습니다.

- **코드 맵 무료 제공, 완전 로컬 작동.** 코드는 tree-sitter AST로 파싱됩니다. 결정론적이며, LLM을 사용하지 않고, 어떤 데이터도 로컬 기기를 떠나지 않습니다. (문서, PDF, 이미지, 동영상은 시맨틱 패스를 위해 어시스턴트의 모델 또는 설정된 API 키를 사용합니다.)
- **모든 연결 관계(edge)에 대한 설명 제공.** 각 연결은 `EXTRACTED`(소스에 명시됨) 또는 `INFERRED`(graphify가 추론함)로 태그가 지정되므로, 직접 읽어온 내용과 추론된 내용을 명확히 구분할 수 있습니다.
- **벡터 인덱스가 아닙니다.** 임베딩도, 벡터 스토어도 없습니다. 탐색 가능한 실제 그래프입니다. 질문을 던지고, 두 개체 사이의 경로를 추적하거나, 하나의 개념을 설명받으세요.

> 요청할 때만 분석하는 것이 아니라, 코드, 문서, 회의록에 걸쳐 백그라운드에서 항상 켜져 있는 상태로 업데이트되기를 원하시나요? 이것이 바로 **[graphify.com](https://graphify.com)**에서 만들고 있는 기능이며, 현재 **[app.graphify.com](https://app.graphify.com/login)**에서 얼리 액세스 참여가 가능합니다.

<img src="https://raw.githubusercontent.com/Graphify-Labs/graphify/v8/docs/graph-hero.png" alt="graphify's interactive graph.html showing the FastAPI codebase as a force-directed knowledge graph with a legend of detected communities" width="900">


 graphify로 매핑된 FastAPI 코드베이스. 모든 노드는 개념을 나타내며, 색상은 감지된 커뮤니티를 의미하고, graph.html에서 전체 항목을 클릭할 수 있습니다.

**시작하기** (30초 소요):

```bash
uv tool install graphifyy      # CLI 설치 (또는: pipx install graphifyy)
graphify install               # AI 어시스턴트에 스킬 등록
```

그런 다음, AI 어시스턴트에서 다음과 같이 입력하세요:

```
/graphify .
```

이것으로 끝입니다. **세 가지 파일**이 생성됩니다:

```
graphify-out/
├── graph.html       모든 브라우저에서 열기 가능 — 노드 클릭, 필터링, 검색 지원
├── GRAPH_REPORT.md  핵심 요약: 주요 개념, 의외의 연결 고리, 추천 질문
└── graph.json       전체 그래프 — 파일을 다시 읽을 필요 없이 언제든지 질의 가능
```

**지원 환경:** Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot 등 15개 이상의 플랫폼 — [플랫폼 선택 방법](#install)을 참고하세요.

---

## 작동 모습 보기

그래프가 구축되면 파일을 직접 읽는 대신 그래프에 질의하게 됩니다. 위의 FastAPI 코드베이스에서 실행한 graphify의 실제 출력 결과입니다:

```text
$ 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
```

모든 연결에는 **신뢰도 태그**(`EXTRACTED` = 소스에 명시됨, `INFERRED` = 분석을 통해 도출됨)가 포함되어 있어 직접 읽은 내용과 추론된 내용을 구별할 수 있습니다. `graphify query "<질문>"`은 자연어 질문에 맞는 하위 그래프를 반환하며, `graphify path A B`는 두 개체가 어떻게 연결되어 있는지 추적합니다.

---

## 주요 기능

기본 제공되는 기능:

| 기능 | 설명 |
|---|---|
| **갓 노드 (God nodes)** | 가장 많이 연결된 핵심 개념으로, 모든 흐름이 통하는 지점을 파악할 수 있습니다. |
| **커뮤니티 (Communities)** | LLM 없이 Leiden 알고리즘을 통해 서브시스템으로 분할된 그래프 |
| **파일 간 링크** | tree-sitter AST를 통해 약 40개 언어에 걸쳐 `calls`, `imports`, `inherits`, `mixes_in` 관계 해결 |
| **질의, 경로, 설명** | `graph.json`을 기반으로 질문하고, 두 개체 간의 경로를 추적하거나 개념을 설명 |
| **근거 및 문서 참조** | `# NOTE:`, `# WHY:` 주석과 ADR/RFC 인용문이 코드와 연결된 일급 노드로 변환됨 |
| **코드를 넘어선 지원** | 문서, PDF, 이미지, 동영상/오디오를 모두 동일한 그래프로 매핑 |
| **로컬 우선(Local-first)** | 코드는 tree-sitter로 로컬에서 파싱되며(LLM 미사용, 기기 외부로 데이터 유출 없음); 문서/미디어에 대한 시맨틱 패스만 사용자가 설정한 경우 백엔드를 호출 |

---

## 벤치마크

| 벤치마크 | 지표 | graphify | 비교 대상 (Field) |
|---|---|---|---|
| LOCOMO (n=300) | recall@10 | **0.497** | mem0 0.048, supermemory 0.149 |
| LOCOMO (n=300) | QA 정확도 | 45.3% | supermemory 49.7%, mem0 27.3% |
| LongMemEval-S (n=50) | QA 정확도 | **76%** | 밀집 RAG(dense RAG)와 동률 |
| 그래프 빌드 | LLM 크레딧 | **0** | 대부분의 시스템은 토큰당 과금 |

모든 시스템은 동일한 모델과 예산이 적용된 동일한 하네스에서 실행되었으며, 두 명의 평가자에 의해 블라인드 검증된 판사 모델을 통해 채점되었습니다 (90.6% 일치율, 코헨의 카파 계수 0.81). 전체 시스템별 표, 코드 인텔리전스 결과 및 재현 명령어는 **[BENCHMARKS.md](./BENCHMARKS.md)**에서 확인하실 수 있습니다.

---

## 사전 요구 사항

| 요구 사항 | 최소 버전 | 확인 방법 | 설치 방법 |
|---|---|---|---|
| Python | 3.10+ | `python --version` | [python.org](https://www.python.org/downloads/) |
| uv *(권장)* | 제한 없음 | `uv --version` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| pipx *(대체)* | 제한 없음 | `pipx --version` | `pip install pipx` |

**macOS 빠른 설치 (Homebrew):**
```bash
brew install python@3.12 uv
```

**Windows 빠른 설치:**
```powershell
winget install astral-sh.uv
```

**Ubuntu/Debian:**
```bash
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단계 — 패키지 설치:**

```bash
# 권장 (격리된 환경; 설치 후 'graphify'를 찾을 수 없는 경우: uv tool update-shell 실행):
uv tool install graphifyy

# 대체 방법:
pipx install graphifyy
pip install graphifyy  # PATH 설정이 필요할 수 있음 — 아래 참고 사항 참조
```

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

```bash
graphify install
```

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

사용자 프로필 대신 현재 저장소에 어시스턴트 스킬을 설치하려면 `--project` 플래그를 추가하세요:

```bash
graphify install --project
graphify install --project --platform codex
```

프로젝트 범위 설치는 현재 디렉토리 아래에 파일(예: `.claude/skills/graphify/SKILL.md` 또는 `.agents/skills/graphify/SKILL.md` 및 스킬이 필요할 때 로드하는 `references/` 사이드카)을 작성하고, 커밋할 수 있는 파일에 대한 `git add` 힌트를 출력합니다. 프로젝트 범위 설치를 지원하는 플랫폼별 명령어 역시 동일한 플래그를 지원합니다(예: `graphify claude install --project` 또는 `graphify codex install --project`).

> **PowerShell 참고 사항:** `/graphify .` 대신 `graphify .`를 사용하세요. PowerShell에서는 슬래시(`/`)가 경로 구분자로 사용됩니다.

> **`graphify: command not found` 오류가 발생하나요?** `uv tool install`이나 `pipx install`은 `graphify` 명령어를 툴 바이너리 디렉토리(`~/.local/bin`)에 배치합니다. 설치 직후 셸에서 이를 찾지 못하는 경우(신규 macOS + zsh 환경에서 흔히 발생), 해당 디렉토리가 아직 `PATH`에 등록되지 않은 것입니다. `uv tool update-shell`(또는 `pipx ensurepath`)을 실행한 후 새 터미널을 여세요. 기본 `pip`을 사용하는 경우, `~/.local/bin`(Linux) 또는 `~/Library/Python/3.x/bin`(Mac)을 `PATH`에 추가하거나 `python -m graphify`를 실행하세요.

> **설치 대신 `uvx` / `uv tool run`으로 실행하시나요?** 명령어가 아닌 패키지 이름을 지정해야 합니다: `uvx --from graphifyy graphify install`. 그냥 `uvx graphify …`로 실행하면 (`No solution found … no versions of graphify`와 같은) 오류가 발생합니다. `uv tool run`은 첫 번째 단어를 *패키지*로 읽어들이는데 패키지명은 `graphifyy`이기 때문이며, `graphify` 명령어는 그 내부에 포함되어 있습니다.

> **Mac/Windows에서는 가능하면 `pip install`을 피하세요.** 스킬은 런타임에 `graphify-out/.graphify_python`에서 Python을 찾습니다. 이 경로가 `pip`이 패키지를 설치한 환경과 다른 환경을 가리키는 경우 `ModuleNotFoundError: No module named 'graphify'` 오류가 발생합니다. `uv tool install`과 `pipx install`은 자체 환경에서 패키지를 격리하므로 이러한 문제를 완전히 방지할 수 있습니다.

> **Git 훅과 uv tool / pipx:** `graphify hook install`은 설치 시점에 현재 인터프리터 경로를 훅 스크립트에 직접 내장하므로, `~/.local/bin`이 PATH에 없는 GUI Git 클라이언트나 CI 러너에서도 커밋 후 훅(post-commit hook)이 정상적으로 작동합니다. graphify를 재설치하거나 업그레이드한 경우, 내장된 경로를 갱신하려면 `graphify hook install`을 다시 실행하세요.

> **엄격 모드 (Claude Code):** `graphify install --project --strict`를 사용하면 어시스턴트가 실제로 그래프를 강제로 사용하게 됩니다. 기본 설치는 파일을 읽기 전에 `graphify query`를 실행하도록 *유도(nudge)*하는 반면, 엄격 모드는 세션의 첫 번째 원본 소스 읽기를 *차단*하고 그래프로 리디렉션한 후 유도 모드로 전환합니다(따라서 세션당 최대 한 번만 실행되며 멈추지 않습니다). 런타임에 `GRAPHIFY_HOOK_STRICT=1`/`0`으로 토글할 수 있으며, 기본 설치 설정은 변경되지 않습니다(부드러운 유도).

<details>
<summary>플랫폼 선택 (20개 이상의 어시스턴트 지원, 펼치려면 클릭)</summary>

| 플랫폼 | 설치 명령어 |
|----------|----------------|
| Claude Code (Linux/Mac) | `graphify install` |
| Claude Code (Windows) | `graphify install` (자동 감지) 또는 `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 (크로스 프레임워크) | `graphify install --platform agents` (별칭 `--platform skills`) |
| Kiro IDE/CLI | `graphify kiro install` |
| Pi 코딩 어시스턴트 | `graphify install --platform pi` |
| Cursor | `graphify cursor install` |
| Devin CLI | `graphify devin install` |
| Google Antigravity | `graphify antigravity install` |

Codex 사용자는 병렬 추출을 위해 `~/.codex/config.toml`의 `[features]` 아래에 `multi_agent = true`를 설정해야 합니다. CodeBuddy는 Claude Code와 동일한 Agent 툴 및 PreToolUse 훅 메커니즘을 사용합니다. Factory Droid는 병렬 서브에이전트 디스패치를 위해 `Task` 툴을 사용합니다. OpenClaw와 Aider는 순차적 추출을 사용합니다(해당 플랫폼에서 병렬 에이전트 지원은 아직 초기 단계입니다). Trae는 병렬 서브에이전트 디스패치를 위해 Agent 툴을 사용하며 `PreToolUse` 훅을 지원하지 **않으므로**, AGENTS.md가 항상 켜져 있는 메커니즘으로 사용됩니다.

`--platform agents` (별칭 `--platform skills`)는 일반적인 크로스 프레임워크 [Agent-Skills](https://github.com/anthropics/skills) 위치를 대상으로 합니다. 전역 설치의 경우 사양의 사용자 전역 `~/.agents/skills/`(`npx skills` 및 사양 준수 프레임워크에서 읽음)를 사용하며, 프로젝트(`--project`) 설치의 경우 `./.agents/skills/`를 사용합니다. 기본 `graphify install`은 의도적으로 단일 플랫폼(Claude Code)으로 유지되며, `.agents/skills`를 읽는 모든 프레임워크에서 스킬을 검색할 수 있도록 하려면 명명된 `agents` 플랫폼을 사용하세요.

> Codex는 `/graphify` 대신 `$graphify`를 사용합니다.

</details>

| 추가 기능 | 추가되는 기능 | 설치 명령어 |
|---|---|---|
| `pdf` | PDF 추출 | `uv tool install "graphifyy[pdf]"` |
| `office` | `.docx` 및 `.xlsx` 지원 | `uv tool install "graphifyy[office]"` |
| `google` | Google Sheets 렌더링 | `uv tool install "graphifyy[google]"` |
| `video` | 동영상/오디오 전사 (faster-whisper + yt-dlp) | `uv tool install "graphifyy[video]"` |
| `mcp` | MCP stdio 서버 | `uv tool install "graphifyy[mcp]"` |
| `neo4j` | Neo4j 푸시 지원 | `uv tool install "graphifyy[neo4j]"` |
| `falkordb` | FalkorDB 푸시 지원 | `uv tool install "graphifyy[falkordb]"` |
| `svg` | SVG 그래프 내보내기 | `uv tool install "graphifyy[svg]"` |
| `leiden` | Leiden 커뮤니티 감지 (Python < 3.13 전용) | `uv tool install "graphifyy[leiden]"` |
| `ollama` | Ollama 로컬 추론 | `uv tool install "graphifyy[ollama]"` |
| `openai` | OpenAI / OpenAI 호환 API | `uv tool install "graphifyy[openai]"` |
| `gemini` | Google Gemini API | `uv tool install "graphifyy[gemini]"` |
| `anthropic` | Anthropic Claude API (`--backend claude`, `ANTHROPIC_API_KEY` 사용) | `uv tool install "graphifyy[anthropic]"` |
| `bedrock` | AWS Bedrock (IAM 사용, API 키 불필요) | `uv tool install "graphifyy[bedrock]"` |
| `azure` | Azure OpenAI Service (`--backend azure`, `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` 사용) | `uv tool install "graphifyy[openai]"` |
| `sql` | SQL 스키마 추출 | `uv tool install "graphifyy[sql]"` |
| `postgres` | 실시간 PostgreSQL 인트로스펙션 (`--postgres DSN`) | `uv tool install "graphifyy[postgres]"` |
| `dm` | BYOND DreamMaker `.dm`/`.dme` AST 추출 (플랫폼에 맞는 빌드된 휠이 없는 경우 C 컴파일러 + `python3-dev`가 필요할 수 있음) | `uv tool install "graphifyy[dm]"` |
| `terraform` | Terraform / HCL `.tf`/`.tfvars`/`.hcl` AST 추출 | `uv tool install "graphifyy[terraform]"` |
| `pascal` | Pascal / Delphi `.pas`/`.dpr`/`.dpk`/`.inc` AST 추출 (더 정확한 `calls`/`inherits` 연결 제공; 없을 경우 정규식 추출기로 대체됨) | `uv tool install "graphifyy[pascal]"` |
| `chinese` | 중국어 쿼리 형태소 분석 (jieba) | `uv tool install "graphifyy[chinese]"` |
| `all` | 위 모든 기능 포함 | `uv tool install "graphifyy[all]"` |

</details>

---

## 어시스턴트가 항상 그래프를 사용하도록 설정하기

그래프를 빌드한 후 프로젝트에서 이 명령어를 한 번 실행하세요:

| 플랫폼 | 명령어 |
|----------|---------|
| 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 (크로스 프레임워크) | `graphify agents install` (별칭: `graphify skills install`) |
| Kiro IDE/CLI | `graphify kiro install` |
| Pi 코딩 어시스턴트 | `graphify pi install` |
| Devin CLI | `graphify devin install` |
| Google Antigravity | `graphify antigravity install` |

이 명령어를 실행하면 어시스턴트가 코드베이스 관련 질문에 대해 전체 보고서를 읽거나 원본 파일을 grep하는 대신, `graphify query "<질문>"`과 같은 범위 지정 쿼리를 우선적으로 사용하여 지식 그래프를 참조하도록 지시하는 작은 설정 파일이 생성됩니다.

- **훅 지원 플랫폼** (Claude Code, Gemini CLI): 검색 스타일의 툴 호출 전에 (또한 Claude Code의 경우 Read/Glob 툴을 통해 소스 파일을 하나씩 읽기 전에) 자동으로 훅이 실행되어 어시스턴트가 그래프 경로를 이용하도록 유도합니다.
- **인스트럭션 파일 플랫폼** (Codex, OpenCode, Cursor 등): 지속형 인스트럭션 파일(`AGENTS.md`, `.cursor/rules/` 등)을 통해 동일한 쿼리 우선 가이드를 제공합니다.

`GRAPH_REPORT.md`는 광범위한 아키텍처 검토를 위해 계속 사용할 수 있습니다.

**CodeBuddy**는 Claude Code와 동일한 두 가지 작업을 수행합니다. 건축 관련 질문에 답하기 전에 CodeBuddy가 `graphify-out/GRAPH_REPORT.md`를 읽도록 지시하는 `CODEBUDDY.md` 섹션을 작성하고, Bash 검색 명령어 및 파일 읽기 전에 실행되는 `PreToolUse` 훅(`.codebuddy/settings.json`)을 설치하여 `graphify query`를 사용하도록 유도합니다.

**Codex**는 이 플랫폼에서 항상 켜져 있는 그래프 가이드를 실제로 수행하는 `AGENTS.md`에 내용을 작성합니다. `graphify codex install`은 `.codex/hooks.json`에 `PreToolUse` 훅(`graphify hook-check`)도 등록하지만, 이 항목은 의도적으로 **아무 동작도 하지 않습니다(no-op)**. Codex 데스크톱은 `PreToolUse`에서 `hookSpecificOutput.additionalContext`를 거부하므로, 해당 위치에서 유도 메시지를 출력하면 Bash 툴 호출이 중단되기 때문입니다. 훅(`graphify hook-guard`)이 유도 역할을 수행하는 Claude Code와 달리, Codex에서는 훅이 실행되더라도 의도적으로 아무 것도 하지 않으며 `AGENTS.md`가 항상 켜져 있는 메커니즘으로 작동합니다.

**Kilo Code**는 Graphify 스킬을 `~/.config/kilo/skills/graphify/SKILL.md`에 설치하고 네이티브 `/graphify` 명령어를 `~/.config/kilo/command/graphify.md`에 설치합니다. 또한 `graphify kilo install`은 `AGENTS.md`와 함께 네이티브 `tool.execute.before` 플러그인(`.kilo/plugins/graphify.js` + `.kilo/kilo.json` 또는 `.kilo/kilo.jsonc` 등록)을 작성하여 Kilo가 네이티브 `.kilo` 설정을 통해 동일한 항상 켜져 있는 그래프 리마인더 동작을 얻을 수 있도록 합니다.

**Cursor**는 `alwaysApply: true`로 `.cursor/rules/graphify.mdc`를 작성하므로, 훅 없이도 Cursor가 모든 대화에 자동으로 이를 포함합니다.

모든 플랫폼에서 graphify를 한 번에 제거하려면 `graphify uninstall`을 실행하세요(`graphify-out/`도 함께 삭제하려면 `--purge` 추가). 또는 플랫폼별 명령어(예: `graphify claude uninstall`)를 사용할 수 있습니다.

---

## 리포트에 포함된 내용

- **갓 노드 (God nodes)** — 프로젝트에서 가장 많이 연결된 개념들입니다. 모든 데이터와 로직이 이 노드들을 거쳐 흐릅니다.
- **의외의 연결 고리 (Surprising connections)** — 서로 다른 파일이나 모듈에 위치한 개체 간의 링크입니다. 예상치 못한 정도에 따라 순위가 매겨집니다.
- **"이유" (The "why")** — 인라인 주석(`# NOTE:`, `# WHY:`, `# HACK:`), 독스트링(docstrings), 그리고 문서의 설계 근거가 추출되어 그 코드를 설명하는 별도의 노드로 연결됩니다.
- **추천 질문 (Suggested questions)** — 그래프가 답변하는 데 특화된 4~5가지 질문입니다.
- **신뢰도 태그 (Confidence tags)** — 추론된 모든 관계에는 `EXTRACTED`, `INFERRED` 또는 `AMBIGUOUS`가 표시됩니다. 어떤 내용이 실제 코드에서 발견되었고 어떤 내용이 추론되었는지 항상 파악할 수 있습니다.

---

## 지원하는 파일 형식

| 유형 | 확장자 |
|------|-----------|
| 코드 (36개의 tree-sitter 문법) | `.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`는 `uv tool install graphifyy[dm]` 필요; `.mts`/`.cts`는 TypeScript 문법 재사용, `.cc`/`.cxx`, CUDA `.cu`/`.cuh`, Metal `.metal`은 C++ 문법 재사용) |
| Salesforce Apex | `.cls .trigger` (정규식 기반; 클래스, 인터페이스, 열거형, 메서드, 트리거, SOQL/DML 연결) |
| Terraform / HCL | `.tf .tfvars .hcl` (`uv tool install graphifyy[terraform]` 필요) |
| MCP 설정 | `.mcp.json` `mcp.json` `mcp_servers.json` `claude_desktop_config.json` — 서버 노드, 패키지 참조, 환경 변수 요구 사항 추출 |
| 패키지 매니페스트 | `apm.yml` `pyproject.toml` `go.mod` `pom.xml` — 패키지당 하나의 표준 패키지 노드(이름 기준) 및 `depends_on` 연결 생성으로, 여러 매니페스트에서 참조되는 패키지를 단일 허브로 관리 |
| 문서 | `.md .mdx .qmd .html .txt .rst .yaml .yml` (마크다운 `[text](./other.md)` 링크와 `[[wikilinks]]`가 문서 간 `references` 연결로 변환됨) |
| 오피스 문서 | `.docx .xlsx` (`uv tool install graphifyy[office]` 필요) |
| Google Workspace | `.gdoc .gsheet .gslides` (옵트인; `gws` 인증 및 `--google-workspace` 필요; 시트의 경우 `uv tool install graphifyy[google]` 필요) |
| PDF | `.pdf` |
| 이미지 | `.png .jpg .webp .gif` |
| 동영상 / 오디오 | `.mp4 .mov .mp3 .wav` 등 (`uv tool install graphifyy[video]` 필요) |
| YouTube / URL | 모든 동영상 URL (`uv tool install graphifyy[video]` 필요) |

코드는 **API 호출 없이 로컬에서** 추출됩니다 (tree-sitter를 통한 AST). 그 외의 항목은 AI 어시스턴트의 모델 API를 통해 처리됩니다.

데스크톱용 Google Drive의 `.gdoc`, `.gsheet`, `.gslides` 파일은 문서 내용 자체가 아니라 바로가기 포인터입니다. 헤드리스 추출에 기본 Google 문서, 시트, 슬라이드를 포함하려면 [`gws` CLI](https://github.com/googleworkspace/cli)를 설치하고 인증한 후 다음을 실행하세요:

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

`GRAPHIFY_GOOGLE_WORKSPACE=1`을 설정할 수도 있습니다. Graphify는 바로가기를 마크다운 사이드카로 `graphify-out/converted/`에 내보낸 후 해당 파일들을 추출합니다.

---

## 주요 명령어

```bash
/graphify .                        # 현재 폴더에 대한 그래프 빌드
/graphify ./docs --update          # 변경된 파일만 다시 추출
/graphify . --cluster-only         # 재추출 없이 클러스터링 재실행
/graphify . --cluster-only --resolution 1.5      # 더 세분화된 커뮤니티 분할
/graphify . --cluster-only --exclude-hubs 99     # 갓 노드 순위에서 유틸리티 슈퍼 허브 제외
/graphify . --no-viz               # HTML 생략, 보고서 및 JSON만 생성
/graphify . --wiki                 # 그래프를 기반으로 마크다운 위키 빌드
graphify export callflow-html      # Mermaid 아키텍처/콜플로우 HTML (훅이 설치된 경우 모든 git commit마다 자동 재생성)

/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

/graphify add https://arxiv.org/abs/1706.03762 # 논문을 가져와서 추가
/graphify add <youtube-url> # 동영상을 전사하여 추가

graphify hook install              # git commit 시 자동 재구축
graphify merge-graphs a.json b.json              # 두 개의 그래프 병합

graphify prs                       # PR 대시보드: CI 상태, 리뷰 상태, 워크트리 매핑
graphify prs 42                    # 그래프 영향도와 함께 PR #42 상세 분석
graphify prs --triage              # AI가 리뷰 대기열 순위 지정 (설정된 백엔드 사용)
graphify prs --conflicts           # 그래프 커뮤니티를 공유하는 PR — 병합 순서 위험도 분석
```

아래의 [전체 명령어 참조](#full-command-reference)를 확인하세요.

---

## 파일 무시하기 (Ignoring files)

프로젝트 루트에 `.graphifyignore` 파일을 생성하세요. `.gitignore`와 동일한 문법을 사용하며 `!` 부정(negation) 문법도 지원합니다.

**`.gitignore`는 자동으로 존중됩니다.** graphify는 각 디렉토리의 `.gitignore`를 읽습니다. `.graphifyignore`도 함께 존재하는 경우 두 파일은 **병합**되며, `.graphifyignore` 패턴이 마지막에 평가되므로 충돌 시 우선권을 갖습니다(`!` 부정 포함). `.graphifyignore`를 추가하면 제외 범위가 늘어나기만 할 뿐, `.gitignore`가 이미 제외한 파일을 다시 포함시키지는 않습니다. 하위 디렉토리 범위 지정은 git과 동일하게 작동하며, 무시 파일은 해당 하위 트리(subtree)에만 영향을 미칩니다.

git으로 무시된 생성된(generated) 코드나 트랜스파일된 코드가 그래프에 포함되어야 하는 경우 `graphify extract`에 `--no-gitignore`를 전달하세요. 이 경우 `.gitignore`와 `.git/info/exclude`가 비활성화되며, `.graphifyignore`는 계속 적용됩니다.

```
# .graphifyignore
node_modules/
dist/
*.generated.py

# src/만 색인화하고 나머지는 모두 무시
*
!src/
!src/**
```

---

## 팀 협업 설정

팀원 모두가 동일한 맵을 가지고 시작할 수 있도록 `graphify-out/`은 git에 커밋하는 것이 좋습니다.

**권장되는 `.gitignore` 추가 항목:**
```
graphify-out/cost.json        # 로컬 전용
# graphify-out/cache/         # 선택 사항: 속도 향상을 위해 커밋하거나, 저장소를 작게 유지하기 위해 제외
```

> `manifest.json`은 이제 이식이 가능합니다. 키가 상대 경로로 저장되고 로드 시 재조정되므로 커밋해도 안전하며 최초 체크아웃 시 전체 재빌드를 피할 수 있습니다.

**작업 흐름:**
1. 한 사람이 `/graphify .`를 실행하고 `graphify-out/`을 커밋합니다.
2. 모든 팀원이 풀(pull)을 받으면 어시스턴트가 그래프를 즉시 읽습니다.
3. `graphify hook install`을 실행하여 각 커밋 후 자동으로 재구축하도록 설정합니다 (AST 전용, API 비용 없음). 또한 Git 병합 드라이버를 설정하여 `graph.json`에 충돌 마커가 남지 않도록 합니다. 병렬로 커밋하는 두 개발자의 그래프가 자동으로 유니온 병합(union-merge)됩니다.
4. 문서나 논문이 변경되면 `/graphify --update`를 실행하여 해당 노드들을 갱신합니다.

---

## 그래프 직접 활용하기

```bash
# 터미널에서 그래프에 질의
graphify query "show the auth flow"
graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json

# 그래프를 MCP 서버로 노출 (반복적인 툴 호출 액세스용)
python -m graphify.serve graphify-out/graph.json
python -m graphify.serve --graph graphify-out/graph.json  # --graph 플래그도 지원됨

# Kimi Code에 등록:
kimi mcp add --transport stdio graphify -- python -m graphify.serve graphify-out/graph.json

# 또는 HTTP로 서빙하여 팀 전체가 하나의 URL을 참조하도록 설정 (로컬 graphify 불필요):
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"
```

MCP 서버를 통해 어시스턴트는 구조화된 액세스를 제공받습니다: `query_graph`, `get_node`, `get_neighbors`, `shortest_path`, `list_prs`, `get_pr_impact`, `triage_prs`.

### 공유 HTTP 서버

`--transport stdio` (기본값)는 개발자별로 로컬 서버를 하나씩 실행합니다. `--transport http`는 동일한 툴을 MCP Streamable HTTP 전송 방식을 통해 제공하므로, 단일 공유 프로세스로 팀 전체의 그래프를 서빙할 수 있습니다. 클라이언트는 로컬에서 graphify를 실행하는 대신 IDE MCP 설정을 `http://<host>:8080/mcp`를 가리키도록 설정하면 됩니다.

| 플래그 | 기본값 | 용도 |
|---|---|---|
| `--transport {stdio,http}` | `stdio` | 서빙할 전송 방식 |
| `--host` | `127.0.0.1` | HTTP 바인드 호스트 (로컬호스트 외부에 노출하려면 `0.0.0.0` 사용) |
| `--port` | `8080` | HTTP 바인드 포트 |
| `--api-key` | 환경 변수 `GRAPHIFY_API_KEY` | `Authorization: Bearer <key>` (또는 `X-API-Key`) 요구 |
| `--path` | `/mcp` | HTTP 마운트 경로 |
| `--json-response` | 꺼짐 | SSE 스트림 대신 일반 JSON 반환 |
| `--stateless` | 꺼짐 | 세션별 상태 유지 안 함 (로드 밸런싱 / CI 배포용) |
| `--session-timeout` | `3600` | N초 동안 유휴 상태인 스테이트풀 세션 정리 (`0`은 비활성화) |

기본 바인드 주소인 `127.0.0.1`은 루프백 전용입니다. 공유 호스트에 노출할 때는 `--host 0.0.0.0`과 `--api-key`를 **함께** 설정하세요. 컨테이너에서 실행하는 방법:

```bash
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 참고 사항:** Ubuntu에는 `python`이 아니라 `python3`가 기본 설치되어 있습니다. 충돌을 방지하려면 가상 환경(venv)을 사용하세요:
> ```bash
> python3 -m venv .venv && .venv/bin/pip install "graphifyy[mcp]"
> ```

---

## 환경 변수

이 변수들은 **헤드리스 / CI 추출**(`graphify extract`) 시에만 필요합니다. IDE 내부에서 `/graphify` 스킬을 통해 실행할 때는 IDE 세션에서 모델 API를 제공하므로 추가 키가 필요하지 않습니다.

| 변수명 | 용도 | 필수 조건 |
|---|---|---|
| `ANTHROPIC_API_KEY` | Claude (Anthropic) 백엔드 | `--backend claude` |
| `ANTHROPIC_BASE_URL` | Anthropic 호환 엔드포인트 URL (LiteLLM 프록시, 게이트웨이 등) | `--backend claude` (기본값: `https://api.anthropic.com`) |
| `ANTHROPIC_MODEL` | Claude 백엔드용 모델 이름 — 커스텀 엔드포인트의 경우 서버가 노출하는 모델 이름/별칭 사용 | `--backend claude` (기본값: `claude-sonnet-4-6`) |
| `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY` | Google Gemini 백엔드 | `--backend gemini` |
| `OPENAI_API_KEY` | OpenAI 또는 OpenAI 호환 API | `--backend openai` (로컬 서버는 빈 값이 아닌 경우 모두 허용) |
| `OPENAI_BASE_URL` | OpenAI 호환 서버 URL (llama.cpp, vLLM, LM Studio 등) | `--backend openai` (기본값: `https://api.openai.com/v1`) |
| `OPENAI_MODEL` | OpenAI 백엔드용 모델 이름 — 자체 호스팅 서버의 경우 서버가 노출하는 모델 이름/별칭 사용 (서버의 `/v1/models` 엔드포인트 확인), 예: llama.cpp의 경우 `LFM2.5-8B-A1B-UD-Q4_K_XL` | `--backend openai` (기본값: `gpt-4.1-mini`) |
| `DEEPSEEK_API_KEY` | DeepSeek 백엔드 | `--backend deepseek` |
| `MOONSHOT_API_KEY` | Kimi Code 백엔드 | `--backend kimi` |
| `OLLAMA_BASE_URL` | Ollama 로컬 추론 URL | `--backend ollama` (기본값: `http://localhost:11434`) |
| `OLLAMA_MODEL` | Ollama 모델 이름 | `--backend ollama` (기본값: 자동 감지) |
| `GRAPHIFY_OLLAMA_NUM_CTX` | Ollama KV 캐시 윈도우 크기 재정의 | 선택 사항 — 기본적으로 자동 크기 지정 |
| `GRAPHIFY_OLLAMA_KEEP_ALIVE` | Ollama 모델을 메모리에 유지할 시간(분) | 선택 사항 — 각 청크 후 언로드하려면 `0` 설정 |
| `AZURE_OPENAI_API_KEY` | Azure OpenAI Service 백엔드 | `--backend azure` |
| `AZURE_OPENAI_ENDPOINT` | Azure 리소스 엔드포인트 URL | `--backend azure` (API 키와 함께 필수) |
| `AZURE_OPENAI_API_VERSION` | Azure API 버전 재정의 | 선택 사항 — 기본값 `2024-12-01-preview` |
| `AZURE_OPENAI_DEPLOYMENT` 또는 `GRAPHIFY_AZURE_MODEL` | Azure 배포 이름 | 선택 사항 — 기본값 `gpt-4o` |
| `AWS_*` / `~/.aws/credentials` | AWS Bedrock — 표준 자격 증명 체인 | `--backend bedrock` (API 키 불필요, IAM 사용) |
| `GRAPHIFY_MAX_WORKERS` | AST 병렬 처리 스레드 수 | 선택 사항 — `--max-workers` 플래그로도 지정 가능 |
| `GRAPHIFY_MAX_OUTPUT_TOKENS` | 조밀한 코퍼스(dense corpora)에 대한 출력 상한 상향 | 선택 사항 — 대용량 파일의 경우 예: `32768` |
| `GRAPHIFY_API_TIMEOUT` | HTTP, claude-cli, Anthropic SDK 및 Bedrock 백엔드의 호출당 타임아웃(초) (기본값: 600) | 선택 사항 — `--api-timeout` 플래그로도 지정 가능 |
| `GRAPHIFY_MAX_RETRIES` | 속도 제한(429) 요청을 포기하기 전에 재시도할 횟수 (기본값: 6; `Retry-After` 준수) | 선택 사항 — 엄격한 조직별 제한(예: kimi)의 경우 값을 상향; `0`은 비활성화 |
| `GRAPHIFY_FORCE` | 노드 수가 적더라도 그래프 강제 재구축 | 선택 사항 — `--force` 플래그로도 지정 가능 |
| `GRAPHIFY_GOOGLE_WORKSPACE` | Google Workspace 자동 내보내기 활성화 | 선택 사항 — `1`로 설정 |
| `GRAPHIFY_TRIAGE_BACKEND` | `graphify prs --triage`용 백엔드 | 선택 사항 — 사용 가능한 키에서 자동 감지 |
| `GRAPHIFY_TRIAGE_MODEL` | 트리아지용 모델 재정의 | 선택 사항 — 예: `claude-opus-4-7` |
| `GRAPHIFY_QUERY_LOG_ENABLE` | `~/.cache/graphify-queries.log`에 로컬 쿼리 로그 기록을 켜려면 `1`로 설정 (각 쿼리/경로/설명 질문 + 코퍼스 경로 기록). 기본값은 꺼짐 — 옵트인하지 않으면 아무것도 기록되지 않음 (#1797) | 선택 사항 |
| `GRAPHIFY_QUERY_LOG` | 쿼리 로그를 활성화하고 기본 경로 대신 이 경로에 기록 | 선택 사항 — 이 변수나 `_ENABLE`이 설정되지 않은 경우 꺼짐 |
| `GRAPHIFY_QUERY_LOG_DISABLE` | 쿼리 로그를 강제로 끄려면 `1`로 설정 (활성화 변수보다 우선 적용) | 선택 사항 |
| `GRAPHIFY_QUERY_LOG_RESPONSES` | 로그가 활성화된 경우 전체 하위 그래프 응답도 함께 기록 (기본값: 꺼짐) | 선택 사항 |
| `GRAPHIFY_MAX_GRAPH_BYTES` | 512 MiB graph.json 크기 제한 재정의 — 예: `700MB`, `2GB` 또는 바이트 단위 정수 | 선택 사항 — 매우 큰 코퍼스에 유용함 |
| `GRAPHIFY_MAX_CONTEXTS` | 단일 멀티 프로젝트 MCP 서버가 유지하는 비기본 프로젝트 그래프의 최대 수 | 선택 사항 — 기본값: `8`; 잘못된 값은 `8`을 사용하고 `1` 미만의 값은 `1`로 처리됨 |
| `GRAPHIFY_LLM_TEMPERATURE` | 시맨틱 추출을 위한 LLM 온도 재정의 — 예: `0.7` 또는 생략하려면 `none` | 선택 사항 — o1/o3/o4/gpt-5 추론 모델의 경우 자동 생략됨 |

---

## 프라이버시

- **코드 파일** — tree-sirtter를 통해 로컬에서 처리됩니다. 어떤 데이터도 기기를 떠나지 않습니다. 코드 전용 코퍼스는 API 키가 필요하지 않으며, `graphify extract`가 완전히 오프라인으로 실행됩니다. 혼합 리포지토리의 경우 `--code-only`를 추가하여 코드만 색인화하고 LLM이 필요한 문서/PDF/이미지는 건너뛸 수 있습니다.
- **동영상 / 오디오** — faster-whisper를 사용하여 로컬에서 전사됩니다. 어떤 데이터도 기기를 떠나지 않습니다.
- **문서, PDF, 이미지** — 시맨틱 추출을 위해 AI 어시스턴트로 전송됩니다(IDE 세션이 실행 중인 모델을 사용하는 `/graphify` 스킬을 통해). 헤드리스 `graphify extract`에는 `GEMINI_API_KEY`/`GOOGLE_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` 플래그도 동일한 키를 사용합니다.
- **데이터 주권 (Data residency)** — `graphify extract`는 설정된 API 키를 기반으로 사용할 공급자를 자동으로 감지합니다 (우선순위: Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama). 데이터 주권 요구 사항이 있는 코드의 경우 `--backend ollama`(완전 로컬)를 사용하거나 명시적인 `--backend` 플래그를 전달하세요. Kimi(`MOONSHOT_API_KEY`)는 중국의 Moonshot AI 서버로 라우팅됩니다.
- **원격 분석(Telemetry) 없음**, 사용량 추적 없음, 분석 도구 없음.
- **쿼리 로깅** — 모든 `graphify query`, `graphify path`, `graphify explain` 및 MCP `query_graph` 호출은 JSON Lines 형식으로 `~/.cache/graphify-queries.log`에 기록됩니다 (타임스탬프, 질문, 코퍼스, 반환된 노드, 소요 시간). 전체 하위 그래프 응답은 기본적으로 **저장되지 않습니다**. 옵트아웃하려면 `GRAPHIFY_QUERY_LOG_DISABLE=1`을 설정하거나, 코드 경로를 비활성화하지 않고 조용히 처리하려면 `GRAPHIFY_QUERY_LOG=/dev/null`을 설정하세요.

---

## 문제 해결 (Troubleshooting)

**설치 후 `graphify: command not found` 오류 발생**
CLI가 설치되었으나 해당 바이너리 디렉토리가 셸의 `PATH`에 등록되지 않은 경우입니다. 설치 방식에 따라 다음 해결책을 적용하세요:
- **uv** (`uv tool install graphifyy`): 명령어가 uv의 툴 bin 디렉토리(`~/.local/bin`)에 배치되는데, 새로운 macOS/zsh 설정에서는 이 경로가 종종 `PATH`에 포함되어 있지 않습니다. `uv tool update-shell`을 실행한 후 새 터미널을 여세요. (`uv tool dir --bin`으로 디렉토리 확인 가능)
- **pipx** (`pipx install graphifyy`): `pipx ensurepath`를 실행한 후 새 터미널을 여세요.
- **pip** (`pip install graphifyy`): pip은 `PATH`에 없을 수 있는 사용자 bin 디렉토리에 스크립트를 설치합니다. `~/.zshrc`/`~/.bashrc`의 `PATH`에 `~/Library/Python/3.x/bin`(macOS) 또는 `~/.local/bin`(Linux)을 추가하거나 `python -m graphify`를 실행하세요.

**`uvx graphify …` 또는 `uv tool run graphify …`에서 `graphify`를 해결하지 못하는 문제**
PyPI 패키지명은 `graphifyy`이며, `graphify`는 해당 패키지가 제공하는 명령어일 뿐입니다. `uv tool run`은 첫 번째 단어를 *패키지 이름*으로 취급하므로 `graphify`라는 패키지를 찾아 `No solution found … no versions of graphify` 오류를 보고합니다. 패키지 이름을 명시적으로 지정하세요: `uvx --from graphifyy graphify install` (`uv tool run --from graphifyy graphify install`과 동일). 또는 `uv tool install graphifyy`를 한 번 실행한 후 `graphify`를 직접 호출하세요.

**`uv run --with graphifyy python -m graphify`가 조용히 이전 설치 버전을 실행하는 문제**
`uv run`은 *시스템* Python을 사용하므로, 시스템에 예전 `graphifyy` 버전이 남아 있는 경우(예: 과거의 `pip install graphifyy`), Python이 `sys.path`에서 해당 버전을 먼저 찾아 `--with graphifyy`가 무시됩니다. 오류 없이 실행되지만 *구버전*의 동작으로 작동하게 됩니다(예: `OPENAI_BASE_URL` 같은 환경 변수 재정의가 무시되어 요청이 기본 엔드포인트로 향하고 잘못된 키처럼 보이는 401 오류 발생). 이 경우 `warning: skill is from graphify <newer>, package is <older>` 경고 라인이 출력됩니다. 이는 오래된 스킬이 아니라 다른 설치본이 로드되었음을 의미합니다. 실제로 로드된 복사본을 확인하려면 다음을 실행하세요:
```bash
python -c "import graphify; print(graphify.__file__)"
```
그런 다음 설치된 명령어를 직접 실행하거나(uv 관리 복사본 사용됨), 오래된 시스템 복사본을 제거하세요:
```bash
uvx --from graphifyy graphify extract . --backend openai # 패키지 이름 명시
pip uninstall graphifyy # 또는 오래된 시스템 설치 제거
```

**`python -m graphify`는 작동하지만 `graphify` 명령어는 작동하지 않는 경우**
셸의 `PATH`에 명령어가 설치된 bin 디렉토리가 포함되어 있지 않습니다. 일반 `pip` 대신 `uv tool install` / `pipx install`을 사용한 후 `uv tool update-shell` / `pipx ensurepath`를 실행하고 새 터미널을 여세요 (위의 설치 참고 사항 참조).

**PowerShell에서 `/graphify .` 실행 시 "path not recognized" 오류 발생**
PowerShell은 슬래시(`/`)를 경로 구분자로 취급합니다. Windows에서는 슬래시 없이 `graphify .`를 사용하세요.

**`--update` 또는 재구축 후 그래프의 노드 수가 줄어든 경우**
리팩토링으로 인해 파일이 삭제된 경우 예전 노드가 남아있을 수 있습니다. 새 그래프의 노드 수가 더 적더라도 덮어쓰려면 `--force`를 전달하세요 (`GRAPHIFY_FORCE=1` 설정).

**`extract`가 "extraction was incomplete ... refusing to overwrite" 메시지와 함께 종료되는 경우**
추출 과정에서 충돌이 발생하거나 워크(walk)가 코퍼스를 완전히 읽지 못한 경우, 생성된 결과가 완전한 결과보다 작기 때문에 `graphify extract`가 기존의 더 큰 그래프가 부분적인 결과로 덮어씌워지는 것을 거부합니다(`graph.json` 보호). 근본적인 원인을 해결한 후 다시 실행하거나, 강제로 덮어쓰려면 `--allow-partial`을 전달하세요.

**동일한 엔티티에 대해 중복된 노드가 생성되는 경우 (고스트 중복)**
고스트 중복(동일한 심볼이 소스 위치가 있는 AST 추출에서 한 번, 소스 위치가 없는 시맨틱 추출에서 한 번 나타나는 현상)은 이제 빌드 시점에 자동으로 병합됩니다. v0.8.33 이전 버전에서 빌드된 그래프에서 이 현상이 관찰되는 경우 전체 재추출을 실행하여 정리하세요:
```bash
graphify extract . --force
```

**Ollama VRAM 부족 / 컨텍스트 윈도우 초과 오류**
KV 캐시 윈도우가 자동으로 크기가 지정되지만 사용 중인 GPU에 비해 너무 클 수 있습니다. 값을 줄이세요:
```bash
GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama --token-budget 4000
```

**`LLM returned invalid JSON` / `Unterminated string` 경고**
모델의 JSON 응답이 출력 토큰 제한에 도달하여 중간에 잘린 경우입니다. graphify는 자동 복구 기능을 제공하므로 (청크를 분할하고 절반씩 다시 추출하며, 너무 큰 단일 문서는 헤딩/단락 경계에서 먼저 조각내어 전체 파일이 여전히 커버되도록 함) 이 경고들은 노이즈일 뿐 데이터 손실이 아닙니다. 이러한 현상을 줄이려면 출력 상한을 높이거나 각 청크의 출력을 줄이세요:
```bash
GRAPHIFY_MAX_OUTPUT_TOKENS=16384 graphify extract . --mode deep   # 상한 상향
graphify extract . --mode deep --token-budget 4000                # 더 작은 입력 청크 -> 더 작은 출력
```
OpenRouter와 같은 클라우드 게이트웨이를 사용하는 경우 Ollama 심글 대신 `--backend openai`(`OPENAI_BASE_URL` 설정)를 선호하세요. 더 깔끔한 OpenAI 호환 경로입니다. 모델 자체에 최대 출력 제한이 있는 경우 `--token-budget`을 낮추는 것이 확실한 방법입니다.

**브라우저에서 열기에 그래프 HTML이 너무 큰 경우 (>5000개 노드)**
HTML 생성을 건너뛰고 JSON을 직접 사용하세요:
```bash
graphify cluster-only ./my-project --no-viz
graphify query "..."
```

**두 명의 개발자가 동시에 커밋한 후 `graph.json`에 충돌 마커가 생기는 경우**
`graphify hook install`을 실행하세요. 충돌이 절대 발생하지 않도록 `graph.json`을 자동으로 유니온 병합(union-merge)하는 Git 병합 드라이버를 설정해 줍니다.

**문서나 PDF 추출 시 노드/연결이 비어 있는 경우**
문서, PDF, 이미지에는 LLM 호출이 필요합니다. 코드 전용 코퍼스에는 키가 필요 없습니다. API 키가 설정되어 있고 백엔드가 올바른지 확인하세요:
```bash
ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claude
```

**IDE에서 스킬 버전 불일치 경고가 발생하는 경우**
설치된 graphify 버전이 스킬 파일과 다릅니다. 업데이트하세요:
```bash
uv tool upgrade graphifyy
graphify install  # 스킬 파일 덮어쓰기
```

**모든 `graphify extract` 실행 후 Claude Code 프롬프트 캐시가 무효화되는 경우**
Graphify는 출력 파일(`graph.json`, `graphify-out/`)을 워크스페이스 내에 기록합니다. 해당 경로가 무시되지 않은 경우, 쓰기가 발생할 때마다 Claude Code의 프롬프트 캐시가 무효화되어 다음 턴에 캐시 쓰기 비용으로 전체 재업로드가 강제됩니다. `.claudeignore`에 추가하세요:
```text
# .claudeignore
graph.json
graphify-out/
```

---

## 전체 명령어 참조

```
/graphify                          # 현재 디렉토리에서 실행
/graphify ./raw                    # 특정 폴더에서 실행
/graphify ./raw --mode deep        # 더 공격적인 관계 추출
graphify extract ./raw --code-only # 코드만 색인화 — 로컬 AST, API 키 불필요 (문서/PDF/이미지 건너뜀); 스킬 플래그가 아닌 extract 플래그
/graphify ./raw --update           # 변경된 파일만 다시 추출
/graphify ./raw --directed         # 에지 방향 유지
/graphify ./raw --cluster-only     # 기존 그래프에서 클러스터링 재실행
/graphify ./raw --no-viz           # HTML 시각화 생략
/graphify ./raw --obsidian         # Obsidian 볼트 생성
/graphify ./raw --obsidian --obsidian-dir ~/vault  # 기존 볼트에 작성 (사용자 노트나 .obsidian 설정은 절대 덮어쓰지 않음)
/graphify ./raw --wiki             # 에이전트 크롤링 가능한 마크다운 위키 빌드
/graphify ./raw --svg              # graph.svg 내보내기
/graphify ./raw --graphml          # Gephi / yEd용 내보내기
/graphify ./raw --neo4j            # Neo4j용 cypher.txt 생성
/graphify ./raw --neo4j-push bolt://localhost:7687
/graphify ./raw --falkordb         # FalkorDB용 cypher.txt 생성
/graphify ./raw --falkordb-push falkordb://localhost:6379
/graphify ./raw --watch            # 파일 변경 시 자동 동기화
/graphify ./raw --mcp              # MCP stdio 서버 시작

/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   # Q&A 결과 기록 (작업 메모리; outcome ∈ useful|dead_end|corrected)
graphify reflect                   # graphify-out/memory/ 결과를 반영하여 reflections/LESSONS.md 생성
graphify reflect --if-stale        # LESSONS.md가 이미 모든 입력보다 최신인 경우 노옵(no-op) (각 세션마다 실행해도 부담 없음)
graphify reflect --out docs/LESSONS.md    # 레슨 문서를 다른 경로에 작성
graphify reflect --graph graphify-out/graph.json  # 커뮤니티별로 레슨을 그룹화하고 작업 메모리 오버레이(.graphify_learning.json) 작성;
                                   # 오버레이는 노드를 preferred/tentative/contested로 태그 지정 (최신 가중치 적용, 출처 포함);
                                   # 이후 graphify explain / query 시 "Lesson:" 힌트를 표시하며 소스가 이동한 경우 "code changed — re-verify"로 플래그 지정

graphify uninstall                 # 모든 플랫폼에서 한 번에 제거
graphify uninstall --purge         # graphify-out/도 함께 삭제
graphify uninstall --project --platform codex  # 프로젝트 범위의 설치 파일만 제거

graphify hook install              # post-commit + post-checkout 훅
graphify hook uninstall
graphify hook status

# 항상 켜져 있는 어시스턴트 인스트럭션 - 플랫폼별 명령어
graphify claude install            # CLAUDE.md + PreToolUse 훅 (Claude Code)
graphify claude uninstall
graphify codebuddy install         # CODEBUDDY.md + PreToolUse 훅 (CodeBuddy)
graphify codebuddy uninstall
graphify codex install             # AGENTS.md + .codex/hooks.json의 PreToolUse 훅 (Codex)
graphify opencode install          # AGENTS.md + tool.execute.before 플러그인 (OpenCode)
graphify kilo install              # 네이티브 Kilo 스킬 + /graphify 명령어 + AGENTS.md + .kilo 플러그인
graphify kilo uninstall
graphify cursor install            # .cursor/rules/graphify.mdc (Cursor)
graphify cursor uninstall
graphify gemini install            # GEMINI.md + BeforeTool 훅 (Gemini CLI)
graphify gemini uninstall
graphify copilot install           # 스킬 파일 (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               # 스킬 파일 (Amp)
graphify amp uninstall
graphify agents install            # ~/.agents/skills/ + AGENTS.md (크로스 프레임워크; 별칭: graphify skills)
graphify agents uninstall
graphify kiro install               # .kiro/skills/ + .kiro/steering/graphify.md (Kiro IDE/CLI)
graphify kiro uninstall
graphify pi install                # 스킬 파일 (Pi 코딩 어시스턴트)
graphify pi uninstall
graphify devin install             # 스킬 파일 + .windsurf/rules/graphify.md (Devin CLI)
graphify devin uninstall
graphify antigravity install       # .agents/rules + .agents/workflows (Google Antigravity)
graphify antigravity uninstall

graphify extract ./docs                        # CI용 헤드리스 LLM 추출 (IDE 불필요)
graphify extract ./docs --backend gemini       # 명시적 백엔드: gemini, kimi, claude, openai, deepseek, ollama, bedrock 또는 claude-cli
graphify extract ./docs --backend gemini --model gemini-3.1-pro-preview
graphify extract ./docs --backend ollama       # 로컬 Ollama (OLLAMA_BASE_URL / OLLAMA_MODEL 설정) - 루프백 시 API 키 불필요
OPENAI_BASE_URL=http://localhost:8080/v1 OPENAI_MODEL=my-model graphify extract ./docs --backend openai   # 모든 OpenAI 호환 서버 (llama.cpp, vLLM, LM Studio)
ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_MODEL=my-model graphify extract ./docs --backend claude   # 모든 Anthropic 호환 엔드포인트 (LiteLLM 프록시, 게이트웨이)
GRAPHIFY_OLLAMA_NUM_CTX=32768 graphify extract ./docs --backend ollama   # KV 캐시 윈도우 재정의 (기본적으로 자동 크기 지정)
GRAPHIFY_OLLAMA_KEEP_ALIVE=0 graphify extract ./docs --backend ollama    # 각 청크 후 모델 언로드 (소형 GPU에서 VRAM 절약)
graphify extract ./docs --backend bedrock      # IAM을 통한 AWS Bedrock - API 키 불필요, AWS 자격 증명 체인 사용
graphify extract ./docs --backend claude-cli   # Claude Code CLI를 통한 라우팅 - API 키 불필요, Claude 구독 사용
graphify extract ./docs --backend azure        # Azure OpenAI (AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT 설정)
graphify extract ./docs --max-workers 16       # AST 병렬 처리 (GRAPHIFY_MAX_WORKERS도 동일)
graphify extract --postgres "postgresql://user:pass@host/db"   # 실시간 PostgreSQL 스키마 직접 인트로스펙션
graphify extract ./my-workspace --cargo        # Rust Cargo 워크스페이스 종속성 직접 인트로스펙션
graphify extract ./docs --token-budget 30000   # 로컬/소형 모델을 위한 더 작은 시맨틱 청크
graphify extract ./docs --max-concurrency 2    # 병렬 LLM 호출 수 감소 (로컬 추론 시 유용)
graphify extract ./docs --api-timeout 900      # 느린 로컬 모델을 위한 더 긴 HTTP 타임아웃 (기본값 600초)
graphify extract ./docs --google-workspace     # 추출 전 gws를 통해 .gdoc/.gsheet/.gslides 내보내기
graphify extract ./src --no-gitignore          # git으로 무시된 소스 포함; .graphifyignore는 계속 준수
graphify extract ./docs --mode deep            # 확장된 시스템 프롬프트를 통한 풍부한 시맨틱 추출
graphify extract ./docs --no-cluster           # 원본 추출만 수행, 클러스터링 생략
graphify extract ./docs --timing               # 단계별 소요 시간을 stderr로 출력 (cluster-only에서도 작동)
graphify extract ./docs --force                # 새 그래프의 노드 수가 더 적더라도 graph.json 덮어쓰기 (리팩토링 후 또는 고스트 중복 제거 시 사용)
graphify extract ./docs --dedup-llm            # 모호한 엔티티 쌍에 대한 LLM 판정 (동일한 API 키 사용)
graphify extract ./docs --global --as myrepo   # 추출하여 크로스 프로젝트 전역 그래프에 등록
GRAPHIFY_MAX_OUTPUT_TOKENS=32768 graphify extract ./docs --backend claude  # 조밀한 코퍼스에 대한 출력 상한 상향

graphify export callflow-html # graphify-out/<project>-callflow.html
graphify export callflow-html --max-sections 8 # 생성되는 아키텍처 섹션 상한 설정
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   # 프로젝트 그래프를 ~/.graphify/global-graph.json에 등록
graphify global remove myrepo                         # 전역 그래프에서 프로젝트 제거
graphify global list                                  # 등록된 모든 리포지토리 + 노드/에지 수 표시
graphify global path                                  # 전역 그래프 파일 경로 출력

graphify prs                              # PR 대시보드: CI, 리뷰, 워크트리, 그래프 영향도
graphify prs 42                           # PR #42 상세 분석
graphify prs --triage                     # AI 트리아지 순위 지정 (환경 변수에서 백엔드 자동 감지)
graphify prs --worktrees                  # 워크트리 → 브랜치 → PR 매핑
graphify prs --conflicts                  # 그래프 커뮤니티를 공유하는 PR (병합 순서 위험도)
graphify prs --base main                  # 특정 베이스 브랜치를 타겟으로 하는 PR 필터링
graphify prs --repo owner/repo            # 다른 GitHub 리포지토리를 대상으로 실행
GRAPHIFY_TRIAGE_BACKEND=kimi graphify prs --triage   # 트리아지에 특정 백엔드 사용

graphify clone https://github.com/karpathy/nanoGPT
graphify merge-graphs a.json b.json --out merged.json
graphify --version                                    # 설치된 버전 출력
graphify watch ./src
graphify check-update ./src
graphify update ./src
graphify update ./src --no-cluster  # 클러스터링 생략, 원본 AST 그래프만 작성
graphify update ./src --force       # 새 그래프의 노드 수가 더 적더라도 덮어쓰기
graphify cluster-only ./my-project
graphify cluster-only ./my-project --graph path/to/graph.json  # 커스텀 그래프 경로
graphify cluster-only ./my-project --max-concurrency 16 --batch-size 200  # 병렬 커뮤니티 네이밍 (대규모 그래프)
graphify cluster-only ./my-project --resolution 1.5            # 더 많고 작은 커뮤니티
graphify cluster-only ./my-project --exclude-hubs 99           # 파티셔닝에서 p99 차수 노드 제외
graphify cluster-only ./my-project --no-label                  # "Community N" 플레이스홀더 유지
graphify cluster-only ./my-project --backend=gemini            # 커뮤니티 네이밍용 백엔드
graphify cluster-only ./my-project --backend=gemini --model gemini-2.5-pro  # 특정 모델 지정
graphify label ./my-project                                    # 설정된 백엔드로 커뮤니티 이름 (재)지정
graphify label ./my-project --backend=openai --model gpt-4o   # 특정 백엔드 및 모델 강제 지정
```

> **커뮤니티 이름:** 에이전트(Claude Code, Gemini CLI) 내부에서는 에이전트가 직접 커뮤니티 이름을 지정합니다. 일반 CLI를 실행할 때 `cluster-only`는 설정된 백엔드(내장 또는 커스텀 OpenAI 호환 공급자)를 사용하여 자동으로 이름을 지정합니다. `Community N`을 유지하려면 `--no-label`을 전달하거나, 필요할 때 `graphify label`을 실행하여 이름을 (재)생성할 수 있습니다.

---

## 추가 정보

- [작동 원리 (How it works)](docs/how-it-works.md) — 추출 파이프라인, 커뮤니티 감지, 신뢰도 점수 산정, 벤치마크
- [ARCHITECTURE.md](ARCHITECTURE.md) — 모듈 세부 분석, 언어 추가 방법
- [선택적 통합 (Optional integrations)](docs/docker-mcp-sqlite.md) — Docker MCP Toolkit + SQLite
- [메모리 계층 (The Memory Layer)](https://safishamsi.gumroad.com/l/qetvlo) — graphify의 기반이 되는 철학과 전체 아키텍처에 대한 서적

---

## graphify Enterprise

[**graphify Enterprise**](https://graphify.com)는 graphify 위에 구축된 상시 가동 레이어입니다. 회의, 파일, 문서, 코드 등 전체 작업 컨텍스트에 동일한 그래프 접근 방식을 적용하여 백그라운드에서 지속적으로 업데이트합니다.

수백 개의 대화와 문서를 오가며 일하지만 이를 완전히 재구성할 수 없는 개인과 팀을 위해 만들어졌습니다.

**[graphify.com에서 대기자 명단에 등록하세요](https://graphify.com).** 무료 평가판 곧 출시 예정.

---

<details>
<summary>기여하기 (Contributing)</summary>

### 개발 환경 설정

프로젝트는 개발 워크플로우를 위해 [uv](https://docs.astral.sh/uv/)를 사용합니다. 한 번 설치한 후 다음과 같이 진행하세요:

```bash
git clone https://github.com/safishamsi/graphify.git
cd graphify
git checkout v8                        # 활성 개발 브랜치

# 프로젝트 가상 환경 생성 및 graphify + 모든 추가 기능 + 개발 그룹(pytest) 설치
# (uv는 기본적으로 개발 의존성 그룹을 설치하며, 생략하려면 --no-dev를 전달하세요)
uv sync --all-extras
```

편집 가능(editable) 설치 확인:
```bash
uv run graphify --version
uv run python -c "import graphify; print(graphify.__file__)"
```

### 테스트 실행

```bash
uv run pytest tests/ -q                # 전체 스위트 실행
uv run pytest tests/test_extract.py -q # 단일 모듈 실행
uv run pytest tests/ -q -k "python"    # 이름으로 필터링
```

> macOS 참고 사항: 테스트 스위트에는 `sample.f90`과 `sample.F90` 피스처가 모두 포함되어 있습니다. 대소문자를 구분하지 않는 HFS+ / APFS 파일 시스템에서는 이 파일들이 충돌합니다. 두 Fortran 변형을 동시에 테스트해야 하는 경우 Linux나 Docker 컨테이너에서 실행하세요.

### Git 워크플로우

- 활성 개발은 `v8` 브랜치에서 이루어집니다.
- 커밋 스타일: `fix: <설명>` / `feat: <설명>` / `docs: <설명>`
- PR을 열기 전에 `uv run pytest tests/ -q`를 실행하여 통과하는지 확인하세요.
- 새로운 언어 추출기를 추가하는 경우 `tests/fixtures/`에 피스처 파일을 추가하고 `tests/test_languages.py`에 테스트를 추가하세요.

### 기여할 수 있는 분야

**작동 예시(Worked examples)**가 가장 유용한 기여입니다. 실제 코퍼스에서 `/graphify`를 실행하고, 출력을 `worked/{slug}/`에 저장한 후, 그래프가 제대로 이해한 것과 오해한 것을 솔직하게 다룬 `review.md`를 작성하여 PR을 열어주세요.

**추출 버그** — 입력 파일, 캐시 항목(`graphify-out/cache/`), 그리고 누락되거나 잘못된 부분을 포함하여 이슈를 열어주세요.

모듈별 책임과 언어 추가 방법에 대한 자세한 내용은 [ARCHITECTURE.md](ARCHITECTURE.md)를 참고하세요.

</details>

---

## 커뮤니티 및 링크

graphify

graphify 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

graphify

graphify 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README