CodeGraph – 로컬 코드 지식 그래프로 코딩 에이전트 탐색 비용을 줄이는 도구

왜 필요한가?
핵심 기능
지원 언어와 에이전트
설치와 초기화
언제 쓰면 좋은가?
관련 문서
참고 자료

CodeGraph는 코드베이스를 로컬 지식 그래프로 사전 인덱싱해 코딩 에이전트가 grep, 파일 읽기, 탐색용 서브에이전트 호출에 쓰는 비용을 줄이는 도구다. Claude Code, Cursor, Codex CLI, OpenCode, Hermes Agent를 지원하며 MCP 서버로 연결된다.

왜 필요한가?

대형 저장소에서 코딩 에이전트가 가장 많이 낭비하는 구간은 “어디를 봐야 하는지 찾는 시간”이다. 모델은 처음에 파일 구조를 모르기 때문에 rg, find, Read를 반복하고, 때로는 탐색용 하위 에이전트를 여러 개 띄운다. CodeGraph는 이 탐색 단계를 로컬 인덱스 질의로 바꾼다.

공식 벤치마크는 7개 오픈소스 코드베이스에서 평균 35% 비용 절감, 59% 토큰 절감, 49% 속도 향상, 70% 도구 호출 감소를 보고한다. 효과는 VS Code, Django, Tokio처럼 파일 수가 많은 저장소에서 더 크고, Gin처럼 작은 저장소에서는 상대적으로 작다.

핵심 기능

기능	설명
코드 지식 그래프	심볼 관계, 호출 그래프, 코드 구조를 로컬 SQLite 인덱스로 저장
스마트 컨텍스트 빌딩	진입점, 관련 심볼, 코드 스니펫을 한 번에 반환
전체 텍스트 검색	FTS5 기반으로 이름과 코드 조각을 빠르게 검색
영향도 분석	특정 심볼의 호출자, 피호출자, 변경 영향 범위를 추적
자동 동기화	OS 파일 이벤트 기반 watcher로 인덱스를 최신 상태로 유지
프레임워크 라우트 인식	Django, FastAPI, Express, NestJS, Rails, Spring, SvelteKit 등 라우트와 핸들러 연결
로컬 우선	외부 API 키 없이 로컬에서 동작하고 코드가 외부로 나가지 않음

지원 언어와 에이전트

CodeGraph는 TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, Pascal/Delphi 등 19개 이상 언어를 지원한다.

에이전트 쪽은 Claude Code, Cursor, Codex CLI, OpenCode, Hermes Agent를 자동 설정 대상으로 삼는다. 설치 과정에서 MCP 서버 설정과 에이전트별 지침 파일을 함께 작성한다.

설치와 초기화

Node.js 없이도 OS별 번들 설치가 가능하다.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# npm 사용
npx @colbymchenry/codegraph
npm i -g @colbymchenry/codegraph

프로젝트에서는 인덱스를 초기화한다.

cd your-project
codegraph init -i

비대화형 설치도 지원한다.

codegraph install --yes
codegraph install --target=cursor,claude --yes
codegraph install --target=auto --location=local
codegraph install --print-config codex

언제 쓰면 좋은가?

대형 모노레포를 자주 탐색하는 팀: 파일 수가 많고 아키텍처 질문이 반복될수록 인덱스 효과가 커진다.
코딩 에이전트 비용을 줄이고 싶은 사용자: 탐색용 토큰과 도구 호출을 줄이는 것이 목적일 때 적합하다.
라우트·핸들러·심볼 관계를 자주 추적하는 백엔드 개발자: 단순 텍스트 검색보다 관계형 질의가 유용하다.
코드 외부 반출을 꺼리는 조직: 인덱스가 로컬 SQLite에 저장되고 외부 서비스가 필요 없다.

반대로 작은 저장소나 일회성 스크립트 작업에서는 기본 rg와 파일 읽기만으로도 충분할 수 있다. CodeGraph는 “탐색이 병목인 프로젝트”에서 가치가 크다.

참고 자료

colbymchenry/codegraph — GitHub 공식 저장소

Like?

AI Sparkup