CodeGraph(colbymchenry/codegraph) — AI 코딩 에이전트 툴 호출을 88% 줄이는 로컬 코드 지식 그래프 MCP 정리
78k 스타 오픈소스 CodeGraph(v1.6.4)의 Rust 커널·SQLite FTS5 동작 구조, 공식 벤치마크(툴 호출 88%↓·비용 44%↓)와 주의할 컨텍스트 점유량까지 정리했습니다.

Q. Claude Code나 Cursor가 코드를 찾을 때마다
grep과 파일 읽기를 수십 번 반복해 느리고 토큰을 많이 씁니다. 로컬에서 한 번에 구조만 넘겨줄 방법이 있나요?colbymchenry/codegraph를 프로젝트에 한 번 초기화해 두면 Rust 커널이 심볼과 호출 관계를 로컬 SQLite(.codegraph/codegraph.db)에 미리 인덱싱하고, 에이전트가codegraph_exploreMCP 도구 한 번으로 필요한 원본 코드와 호출 흐름·영향 반경(Blast Radius)까지 받아갑니다. 공식 7개 리포지토리 벤치마크(2026-08 재측정) 기준으로 툴 호출은 88% 줄고 응답 속도는 53% 빨라지며 처리 토큰은 62%, 비용은 44% 줄었습니다.
⚠️ 정확도 가드레일: 이 글은 2026년 11월 22일 기준
colbymchenry/codegraph공식 GitHub 저장소(78,314 Stars · 5,208 Forks · MIT 라이선스)와 2026년 11월 20일 출시된v1.6.4릴리즈 노트를 직접 확인해 작성했습니다. 벤치마크 수치는 Claude Opus 4.8 헤드리스 환경의 7개 오픈소스 리포지토리 측정치이며, 모델·질문 난이도·프로젝트 규모에 따라 체감 폭은 달라질 수 있습니다.
30초 요약
- 100% 로컬 코드 지식 그래프: 외부 서버나 API 키 없이 내 PC의
.codegraph/codegraph.db(SQLite + FTS5)에 함수·클래스·호출·상속·라우팅 관계를 저장합니다. - Rust 커널 + 자동 동기화: TypeScript·Python·Go·Rust·Java·Kotlin·Swift 등 20개 주요 언어를 네이티브 Rust 커널로 파싱하고, 파일 저장 후 300ms 디바운스로 변경분만 증분 동기화합니다.
- 단일 MCP 도구 설계:
codegraph_explore하나만 기본 노출해 에이전트가 도구를 잘못 고르는 실수를 줄이고, Claude Code·Cursor·Codex CLI·Hermes Agent 등 19종 에이전트를codegraph install한 줄로 연결합니다. - 트레이드오프 주의: 왕복 처리 토큰은 62% 줄지만, 한 번에 원문 스니펫과 호출 경로를 돌려주기 때문에 세션 끝 컨텍스트 창 잔류 점유량은 약 80% 더 커질 수 있습니다.
CodeGraph가 해결하는 문제: 파일 탐색 비용
AI 코딩 에이전트가 코드를 수정하기 전에 가장 많은 시간과 비용을 태우는 구간은 '구조 파악' 단계입니다. 보통 에이전트는 함수 이름 하나를 찾기 위해 grep을 돌리고, 파일을 하나씩 열어(Read) 읽은 뒤 호출 경로를 머릿속으로 다시 조립합니다. 공식 저장소 측정에서는 중간 규모 질문 하나를 푸는 데만 최대 43회 툴 호출과 19회 파일 읽기가 발생했습니다.
CodeGraph는 이 탐색 과정을 프로젝트 초기화 한 번으로 앞당겨 둡니다. 코드베이스의 모든 심볼과 호출 엣지, 동적 디스패치(콜백, React 리렌더, 인터페이스 구현체 연결)까지 그래프에 기록해 두기 때문에 에이전트는 파일 트리를 헤매지 않고 필요한 조각만 외과적으로(Surgical Context) 받아 옵니다.

동작 구조와 공식 벤치마크 수치
CodeGraph는 네이티브 Rust 파서, 로컬 SQLite FTS5 저장소, OS 파일 감시 기반 자동 동기화의 3단 구조로 동작합니다.
- 추출(Extraction): 컴파일된 Rust 커널이
tree-sitter문법으로 20개 언어를 파싱해 함수·클래스·메서드 노드와 호출·임포트·상속 엣지를 뽑아냅니다. - 저장 및 해석(Storage & Resolution): 결과는
.codegraph/codegraph.db에 저장되며 프레임워크 라우트(Express, FastAPI, NestJS, Next.js, Elysia 등 20여 종)와 크로스 파일 참조까지 연결합니다. - 실시간 동기화(Auto-Sync): macOS FSEvents, Linux inotify, Windows 이벤트를 감시해 파일이 바뀌면 약 300ms 뒤 변경된 파일만 다시 반영합니다.
| 측정 항목 | VS Code (TS) | Excalidraw (TS) | Tokio (Rust) | Django (Python) | 7개 리포 평균 |
|---|---|---|---|---|---|
| 툴 호출 수 (적용 vs 미적용) | 2 vs 28 | 2 vs 43 | 3 vs 29 | 3 vs 14 | 88% 감소 |
| 파일 읽기 횟수 | 0 vs 12 | 0 vs 18 | 0 vs 19 | 0 vs 8.5 | 0회로 감소 |
| 응답 시간 | 58초 vs 2분 10초 | 45초 vs 2분 42초 | 1분 3초 vs 2분 43초 | 54초 vs 1분 23초 | 53% 단축 |
| 처리 토큰 / 비용 절감 | 토큰 77%↓ / 비용 71%↓ | 토큰 84%↓ / 비용 78%↓ | 토큰 65%↓ / 비용 64%↓ | 토큰 41%↓ / 비용 13%↓ | 토큰 62%↓ / 비용 44%↓ |
(출처: colbymchenry/codegraph 공식 README, 2026-08-05 Claude Opus 4.8 기준 4회 실행 중앙값)

반드시 짚고 넘어가야 할 단서도 있습니다. 처리 토큰(Throughput)은 크게 줄지만, CodeGraph는 한 번의 응답에 관련 함수의 원문 코드와 호출 계보를 통째로 실어 보냅니다. 공식 문서의 잔류 컨텍스트 측정에 따르면 VS Code 기준 세션 종료 시점 컨텍스트 창에 남아 있는 검색 결과는 기존 파일 읽기 방식(18k 토큰)보다 많은 **67k 토큰(평균 약 80% 증가)**이었습니다. 긴 멀티턴 세션을 작은 컨텍스트 창에서 돌릴 때는 이 점을 감안해야 합니다.
설치부터 에이전트 연결까지 3단계 실행법
별도 Node.js 빌드나 복잡한 설정 파일 없이 CLI 설치, 에이전트 연결, 프로젝트 초기화 3줄이면 끝납니다.
# 1) CLI 설치 (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# 2) 설치된 에이전트(Claude Code, Cursor, Codex CLI 등) 자동 감지 및 MCP 연결
codegraph install
# 3) 대상 프로젝트 폴더에서 그래프 인덱스 생성
cd your-project
codegraph init
에이전트가 MCP 서버로 연결되면 기본으로 codegraph_explore 단일 도구만 노출됩니다. 좁은 기능 도구(node, search, callers, impact 등)를 여러 개 열어 두는 것보다 하나의 통합 도구를 주는 편이 에이전트 오작동이 적고 시스템 프롬프트 토큰도 아낄 수 있기 때문입니다. 필요하다면 CODEGRAPH_MCP_TOOLS 환경 변수로 세부 도구를 다시 켤 수 있습니다.
또한 CI 환경이나 커밋 전 점검에서는 codegraph affected 명령이 유용합니다. 예를 들어 git diff --name-only | codegraph affected --stdin --quiet 형태로 변경된 파일이 영향을 미치는 테스트 파일 목록만 뽑아 실행할 수 있습니다. 앞서 다룬 OpenSRE(CI/CD 장애 추적 에이전트) 가이드처럼 배포·테스트 파이프라인을 자동화할 때 함께 붙이기 좋은 구성입니다.

최신 v1.6.4 업데이트와 실무 체크포인트
2026년 11월 20일 공개된 v1.6.4에서는 단일 심볼 질문 비용 절감과 공용 컴퓨터 보안 검증이 강화됐습니다.
- 단일 심볼 질의 최적화:
"who calls toValidURL?"같은 짧은 질문에 불필요한 유사 파일까지 긁어오지 않고 해당 심볼 정의와 실제 사용 라인만 정확히 반환합니다. - Claude Code 프롬프트 훅 가속: 이미 떠 있는 백그라운드 서버에 직접 질의해 매 프롬프트마다 인덱스를 다시 읽는 지연을 없앴습니다.
- 공용 PC 소켓 소유자 검증: 같은 컴퓨터의 다른 사용자가 백그라운드 서버를 가로채지 못하도록 세션마다 실행 주체를 검증합니다.
- Elysia·PHP·Kotlin 확장 및 git 잠금 충돌 해소: Bun 기반 Elysia 라우팅, PHP
DOCUMENT_ROOT인클루드, 최신 Kotlin 문법을 지원하며 동기화 중index.lock충돌을 막았습니다.
구버전에서 codegraph upgrade로 올렸다면 인덱스 포맷 개선이 반영되도록 프로젝트마다 codegraph index를 한 번 다시 실행하는 것이 좋습니다.
토리스의 판단
- 바로 도입할 만한 경우: 모노레포나 수백 개 이상 파일이 얽힌 TypeScript·Python·Go·Rust 프로젝트를 Claude Code·Cursor·Codex로 다루고 있고, 에이전트가 매번 파일을 뒤지느라 첫 답이 느리거나 API 비용이 부담될 때.
- 보류하거나 조심할 경우: 파일 10~20개 남짓한 소규모 스크립트 저장소이거나, 컨텍스트 창 한도가 작은 모델에서 수십 턴 이상 이어지는 장시간 대화를 유지해야 할 때(잔류 컨텍스트 점유량 증가).
- 실무 추천 세팅: 설치 직후 팀 저장소에
.codegraph/가 올라가지 않게codegraph init --local-only옵션을 쓰고, 텔레메트리가 꺼림칙하다면codegraph telemetry off를 함께 실행해 두는 편이 깔끔합니다. 로컬 도구 구성을 더 넓히고 싶다면 토리스 스튜디오 서비스 안내나 MarkItDown 로컬 문서 MCP 정리도 참고해 보세요.
출처
광고
YOUTUBE · TORIS STUDIO