Claude Code·Codex·Cursor에 반복 지시를 내리면 에이전트가 매번 프로젝트를 처음부터 탐색하는 낭비가 생긴다. Graft는 코드베이스를 한 번 그래프로 만들어 에이전트가 재탐색 없이 구조를 재사용하게 하는 오픈소스 컨텍스트 레이어다. GitHub 5,700★을 넘기며 최근 3일간 하루 평균 약 90~178개씩 별이 늘고 있고, 국내에는 개념 소개 글만 있어 설치·보안·제거까지 다룬 글은 아직 없다. 핵심 주의점은 두 가지다. 공식 벤치마크(토큰 42% 절감 등)는 모두 제작사 자체 측정이고, 리눅스 ARM64에서는 네이티브 모듈이 아예 실행되지 않는 공개 이슈(#119)가 있다.
핵심 요약
- 무엇: Graft — tree-sitter 기반 코드 그래프를 만들어 Claude Code/Codex/Cursor/Gemini 등에 연결하는 컨텍스트 레이어 (MIT, npm
@nanonets/graft)- 누구에게: 큰 저장소에서 Claude Code/Codex를 매일 쓰는데 토큰·시간이 반복 탐색으로 낭비된 개발자
- 검증 결과: 임시 홈에 npm 0.16.0 설치·postinstall 점검·실제 홈 무결성 검증 완료. 단, 이 글을 쓴 라즈베리파이(ARM64) 호스트에서는 네이티브 tree-sitter 미지원으로 CLI 실행 불가 — 공식 이슈 #119로 확인
- 보안: 익명 텔레메트리(버킷 처리,
DO_NOT_TRACK=1또는graft telemetry disable로 차단),~/.codex/사용자 레벨 설정 기입(공개 문서화), API 키 불필요(기본 그래프)- 대체재: Serena(코드 내비게이션 MCP)·Graphify와 비교, LSP와는 보완 관계
Graft가 해결하는 반복 탐색 문제
Claude Code에 “인증 버그 고쳐줘”라고 하면 에이전트는 먼저 저장소를 탐색한다. grep으로 용어를 찾고, 파일을 열고, import를 따라가고, 다시 빠져나오는 과정을 반복한다. 한 시간 전에 만들었던 지도를 세션마다 버리고 다시 만드는 셈이다. Graft의 README는 이를 “에이전트는 매번 온보딩한다”고 표현한다.
Graft는 이 탐색을 한 번만 수행해 결과를 저장소 안 graft/ 폴더에 마크다운 노드 그래프로 저장한다. 구조 분석은 tree-sitter로 로컬에서 결정적으로 이뤄지며, 기본 그래프 빌드에는 API 키도 네트워크 호출도 없다. 이후 에이전트는 파일을 열어 읽듯 그래프를 읽어 탐색 비용을 건너뛴다.
작동 구조를 단순화하면 다음과 같다.
graft build— tree-sitter로 심볼·호출·의존 관계를 추출해graft/폴더에 그래프 생성 (LLM 불필요, 무료)graft init— Claude Code(.claude/), Codex(AGENTS.md), Cursor(.cursor/rules/) 등 각 에이전트의 네이티브 설정 파일에 연결- 세션 중 hooks — 프롬프트마다 관련 노드를 컨텍스트로 당기고, 편집 후 그래프를 자동 재동기화
검증 환경과 직접 확인한 사실 (2026-09-07)
이 글의 모든 수치는 2026-09-07 기준 공식 저장소·npm·GitHub API에서 직접 조회한 값이다.
| 항목 | 값 |
|---|---|
| 공식 저장소 | github.com/trailhq/Graft (이전 NanoNets/Graft, 리다이렉트 확인) |
| 라이선스 | MIT (LICENSE 파일 직접 확인) |
| 최신 릴리스 | 0.17.0 (2026-09-02, 커밋 로그) / npm latest 0.16.0 |
| 스타·포크 | 5,769★ / 538 fork (직접 조회) |
| 실측 증가 | 24시간 +178★ (+3.18%), 최근 3일 흐름 하루 53→39→178개 |
| npm 다운로드 | 최근 30일 23,499회, 최근 7일 9,305회 (npm 공개 API) |
| 이슈 활동 | 81개 이슈, 8/27~8/31 사이 다수 클로즈 웨이브, 최신 오픈 2026-09-05 |
| 지원 언어 | 23개 (TS/JS·Python·Go·Java 등 고정밀 8종 + broad tier 15종) |
출처: GitHub API 직접 조회 (2026-09-03~09-06)
임시 홈 격리 설치 검증. 실제 홈의 ~/.claude, ~/.codex, ~/.claude.json, ~/.claude/settings.json 해시를 설치 전후로 비교했다. 격리된 /tmp 홈에 npm 0.16.0 설치 후 네 개 경로 모두 무결성이 유지됐다(UNCHANGED 4/4). postinstall 스크립트(scripts/postinstall.mjs)를 직접 읽었고, 하는 일은 설치 이벤트 기록 한 건뿐임을 확인했다.
ARM64 실행 실패 — 이것이 이 글의 한계다. 이 서버는 라즈베리파이(linux/arm64)다. 설치는 됐지만 CLI 첫 실행에서 No native build was found for platform=linux arch=arm64 에러로 중단됐다. 의존성 [email protected]의 prebuild가 darwin-arm64/darwin-x64/linux-x64/win32-x64만 제공하기 때문이다. 이는 Graft의 공개 이슈 #119 “ARM64 Incompatibilities”(오픈 상태)와 정확히 일치하며, WASM 폴백을 추가하는 PR #214도 아직 머지 전이다. 따라서 이 글은 설치·설정 파일 구조·제거 절차의 문서 검증까지이고, x64 머신에서의 실제 그래프 빌드·토큰 절감 A/B는 독자가 직접 수행해야 한다.
x64 사용자라면 이렇게 재현한다. 리눅스 x64·macOS·윈도우(WSL 포함)에서는 prebuild가 있어 이 단계가 정상 동작한다.
# 임시 디렉터리에서 먼저 확인 (실제 프로젝트에 영향 없음)
mkdir /tmp/graft-trial && cd /tmp/graft-trial
git init && echo 'console.log(1)' > index.js
DO_NOT_TRACK=1 npm install @nanonets/[email protected]
DO_NOT_TRACK=1 ./node_modules/.bin/graft init --dry-run # 변경될 파일 목록만 출력
DO_NOT_TRACK=1 ./node_modules/.bin/graft build # 그래프 생성 (API 키 불필요)Claude Code·Codex·Hermes 연결 방법
Claude Code (가장 깊은 통합). graft init을 실행하면 감지된 에이전트 목록이 뜨고, 선택한 에이전트의 설정 파일에 기입한다. Claude Code는 .claude/skills/graft/SKILL.md, 프로젝트 .mcp.json에 MCP 서버, statusline, hooks까지 설치된다. 기존 CLAUDE.md은 건드리지 않고 .claude/settings.json도 자기 블록만 병합한다고 문서화돼 있다.
Codex. AGENTS.md에 Graft 섹션을 추가하고, ~/.codex/가 있으면 사용자 레벨 config.toml([mcp_servers.graft]), hooks 파일에도 기입한다. 이 부분은 모든 저장소에 적용되는 machine-wide 변경이므로 --no-global 플래그로 프로젝트 한정으로 설치하는 편이 안전하다.
Hermes 포함 기타 에이전트. 표준 MCP 설정에 수동 등록하면 된다. 어떤 에이전트든 MCP 클라이언트라면 다음 JSON을 설정에 넣는다.
{ "mcpServers": { "graft": { "command": "npx", "args": ["-y", "@nanonets/graft", "mcp"] } } }MCP로 노출되는 도구는 6개다: graft_find_code(질문→랭킹된 노드), graft_file_api(파일 시그니처만), graft_trace_calls(호출자 추적), graft_find_all(정규식 검색), graft_repo_map(저장소 지도), graft_check_freshness(그래프 신선도).
설치 시 실제로 바뀌는 경로 정리.
| 대상 | 경로 | 내용 |
|---|---|---|
| 공통 | graft/ | 코드 그래프(로컬 캐시, .gitignore 자동 추가) |
| Claude Code | .claude/skills/graft/SKILL.md, .mcp.json, hooks, statusline | 스킬·MCP·자동동기화 |
| Codex | AGENTS.md, ~/.codex/config.toml, ~/.codex/hooks.json | 안내 섹션·MCP·편집 훅 |
| Cursor | .cursor/rules/graft.mdc | 룰 파일 |
| Gemini | GEMINI.md | 안내 섹션 |
제거·원상복구 절차
Graft는 공식 제거 명령을 제공한다. 이 점이 검증 중 인상적이었던 부분이다.
graft uninstall # 실제 삭제 전에 제거될 항목을 먼저 출력
graft uninstall -y # 실제 삭제 (init의 역연산)
graft uninstall --no-global # ~/.codex 등 저장소 밖 파일은 유지
npm uninstall -g @nanonets/graft # CLI 자체 제거uninstall은 init이 기입한 모든 파일과 설정 항목을 역으로 제거한다. --keep-cache로 그래프 캐시만 남길 수도 있다. 임시 검증 환경에서는 rm -rf /tmp/graft-trial로 폴더째 삭제하면 끝난다.
보안·권한·텔레메트리: 숨기지 않는 정보
- 네트워크 호출 3종만 존재 (TELEMETRY.md 공식 계약): 사용자가 설정한 LLM 요청, 하루 1회 npm 버전 확인, 배치 처리된 사용 통계 1건. 코드·파일 경로·저장소명·심볼·쿼리는 전송하지 않으며, 모든 숫자는 버킷(예: “200-999 files”)으로만 전송된다.
src/telemetry/contract.ts가 화이트리스트를 강제하고 미등록 속성은 전송 전 차단한다. - 텔레메트리 차단:
DO_NOT_TRACK=1환경변수,graft telemetry disable명령, 또는graft init프롬프트에서 체크 해제. CI 환경에서는 자동으로 꺼진다. - postinstall: npm 설치 직후 익명 설치 이벤트 1건을 detached 프로세스로 보낸다. 스크립트 소스를 직접 읽어 확인했고, 설치 실패를 유발하지 않는 구조다.
- 권한 범위: 로컬 파일 읽기·그래프 쓰기가 전부. 데몬·서버 없음.
--deep모드에서만 사용자가 지정한 LLM 제공자로 코드 요약 요청이 나간다(자기 API 키 사용). - machine-wide 변경 주의: Codex 선택 시
~/.codex/전역 설정이 바뀐다. README가 이를 명시하고--no-global회피 경로를 제공하는 것은 투명한 태도다. - 공급망: OpenSSF Scorecard 배지, TypeScript strict, 29개 npm 버전, 기여자 다수. 악성코드 징후는 없었다.
- 비용: 도구 자체 무료(MIT).
--deep사용 시 자기 LLM 키 비용 발생.
Serena·Graphify·LSP와 비교: 어떤 관계인가
| 구분 | Graft | Serena (MCP) | LSP 직접 연결 |
|---|---|---|---|
| 분류 | 컨텍스트 레이어(그래프 사전 구축) | 코드 내비게이션 MCP | 언어 서버 프로토콜 |
| 입력 | 저장소 전체를 사전 빌드 | 심볼 질의 시점 조회 | 심볼 질의 시점 조회 |
| 출력 | 마크다운 노드 그래프 + MCP 6도구 | 정의/참조/기호 편집 도구 | 정의/참조/완성 |
| 정확도 | 제작사 자체 벤치마크(SWE-bench V 54%→66%, 자체 측정) | LSP 기반으로 결정적 | 언어 서버 수준으로 결정적 |
| 수정 가능성 | 그래프는 재생성 가능한 캐시, 노드에 사용자 노트 보존 | — | — |
| 비용 | 기본 무료, –deep만 키 비용 | 무료 | 무료 |
| 데이터 처리 | 로컬 파일 + 설정한 LLM만 | 로컬 | 로컬 |
| 에이전트 연결 | MCP + Claude Code hooks + 다수 CLI 파일 | MCP | MCP 래퍼 필요 |
관계를 명확히 하면: Graft는 grep 반복 탐색에 대한 부분 직접 대체재이고, Serena는 시점 조회형 내비게이션이므로 목적이 겹치는 다른 하위 범주, LSP는 이미 심볼을 아는 경우의 도구라 보완 관계다. Graft 제작사가 HN 스레드에서 공개한 자체 비교로는 Graphify 대비 검색 정확도 MRR 0.73 vs 0.38 — 단 이 역시 자체 측정이다.
안전한 설치 프롬프트 (복사해서 붙여넣으세요)
아래 프롬프트를 Claude Code나 Codex에 붙여 넣으면 안전 절차를 따라 설치를 진행한다. 운영 프로젝트에서 바로 실행하지 말 것.
https://github.com/trailhq/Graft 문서를 읽고 다음 절차로 Graft를 설치해줘.
조건:
1. 버전 고정: @nanonets/[email protected] (npm 레지스트리에서 조회)
2. 먼저 임시 디렉터리(/tmp/graft-trial)에서 검증한다. 실제 프로젝트는 건드리지 마.
3. DO_NOT_TRACK=1 환경변수로 텔레메트리를 끄고 시작한다.
4. graft init --dry-run 출력을 먼저 보여주고, 내가 승인한 파일만 변경한다.
5. ~/.codex/ 전역 설정은 변경 금지 (--no-global 사용).
6. API 키 입력은 절대 요청하지 마. 기본 그래프 빌드만 수행한다.
7. graft build 결과와 graft check 출력을 보여줘.
8. 검증 후 graft uninstall -y와 npm uninstall로 /tmp/graft-trial을 완전히 정리하고,
변경 전후 파일 목록을 비교해 원상복구를 확인해줘.유용한 경우 vs 추천하지 않는 경우
도입을 검토할 만한 상황
- 수백~수천 파일 규모 저장소에서 Claude Code/Codex를 매일 사용한다
- 세션마다 반복 탐색으로 토큰이 급격히 소모된다
- 여러 팀원이 같은 저장소를 에이전트로 다룬다 (wiring만 커밋하면 각자 그래프 생성)
- linux x64·macOS 환경이다
추천하지 않는 상황
- 라즈베리파이 등 linux ARM64 환경 — 현재 실행 불가 (이슈 #119 오픈 중)
- 파일 몇 개짜리 소규모 프로젝트 — 탐색 비용 자체가 작아 이득이 없다
- 제작사 벤치마크 수치를 그대로 보증값으로 받아들이는 용도 — 어디까지나 자체 측정이다
- 텔레메트리가 자동으로 나가는 것이 원칙적으로 거부되는 환경 — 설치 후 즉시 비활성화 필요
설치 전 체크리스트
- [ ] 내 환경이 linux x64 / darwin / win32 인지 확인 (ARM64는 #119 해결 전 불가)
- [ ]
git status로 커밋되지 않은 변경사항 정리 (백업) - [ ] 임시 디렉터리에서
graft init --dry-run먼저 실행 - [ ]
DO_NOT_TRACK=1설정 여부 확인 - [ ] Codex 전역 변경 원치 않으면
--no-global플래그 사용 - [ ]
--deep사용 여부 결정 (LLM 키 비용 발생) - [ ]
graft uninstall시나리오를 미리 dry-run으로 확인
직접 검증한 것과 검증하지 못한 것
직접 검증 완료
- npm 0.16.0 격리 설치, postinstall 소스 점검, 실제 홈 4개 경로 해시 무결성 (UNCHANGED 4/4)
- LICENSE(MIT), README(42KB), TELEMETRY.md 전문 읽기
- 릴리스 타임라인(0.9.0~0.17.0), 커밋 로그(2026-09-02까지), 이슈 81개 활동
- 스타 증가 실측: 24시간 +178 (3일 연속 관측)
- npm 다운로드 공개 API 조회: 월 23,499회
- HN 토론(39pts/44댓글) 원문 확인, 제작자 응답 포함
검증하지 못한 것 (독자 과제)
- x64 환경에서의 실제 그래프 빌드·CLI 동작 (ARM64 호스트 한계)
- 토큰 42% 절감 재현 — 제작사 자체 벤치마크이므로 독자의 프로젝트에서 A/B 필요
--deep모드의 LLM 요약 품질과 비용- 자체 저장소에서의
graft viz시각화 품질
FAQ
Graft는 무료인가?
도구 자체는 MIT 라이선스 무료다. 기본 그래프 빌드는 API 키 없이 로컬에서 돈다. --deep 모드로 LLM 요약을 추가할 때만 자신의 API 키 비용이 발생한다.
정말 토큰이 42% 절감되나?
그 수치는 제작사가 162회 자체 벤치마크와 SWE-bench Verified 50케이스로 측정한 자체 발표 값이다. SWE-bench 결과(정확도 54%→66%)는 공식 채점기를 썼다고 명시하지만, 독립 검증은 아니다. 자기 프로젝트에서 같은 커밋·같은 작업으로 A/B 테스트하는 것이 가장 정확하다.
ARM64 맥(애플 실리콘)에서도 안 되나?
darwin-arm64 prebuild는 존재한다. 안 되는 것은 linux/arm64 조합뿐이다(라즈베리파이, ARM 리눅스 서버, ARM 도커 이미지). 이슈 #119에서 WASM 폴백 PR #214를 준비 중이다.
기존 CLAUDE.md이나 설정이 덮어써지진 않나?
README 명세상 Graft는 자체 섹션만 추가·갱신하고 기존 내용은 건드리지 않는다. statusLine도 Graft 것이 아닌 기존 설정은 그대로 둔다고 문서화돼 있다. 그래도 도입 전 git add로 백업하자.
Serena와 Graft 중 무엇을 쓰야 하나?
이미 심볼 이름을 알고 정의·참조를 추적한다면 Serena(LSP 기반)면 충분하다. “인증이 어디서 처리되나” 같은 개념 질의와 대형 저장소 오리엔테이션이 필요하면 Graft가 목적에 맞다. 둘은 경쟁보다 하위 범주가 다른 관계다.
제거는 깨끗한가?
graft uninstall -y가 init의 역연산을 수행한다. dry-run으로 삭제 목록을 먼저 볼 수 있어 안전하다. npm 전역 설치라면 npm uninstall -g @nanonets/graft로 마무리한다.
공식 참고자료
- Graft 저장소: https://github.com/trailhq/Graft
- npm 패키지: https://www.npmjs.com/package/@nanonets/graft
- 텔레메트리 문서(TELEMETRY.md): https://github.com/trailhq/Graft/blob/main/TELEMETRY.md
- ARM64 이슈 #119: https://github.com/trailhq/Graft/issues/119
- HN 토론 원문: https://news.ycombinator.com/item?id=49299985
- Agent Skills 사양: https://agentskills.io/home
