Claude Code나 Cursor, Codex와 같은 AI 코딩 도구를 일상적으로 사용하다 보면, 누구나 똑같은 벽에 부딪힌다.

"이 기능은 어디에 구현되어 있지?", "인증 플로우를 정리해줘", "이 모듈을 변경하면 무엇에 영향을 미칠까?" —— 이러한 질문을 던질 때마다, AI는 프로젝트 전체를 탐색하기 시작한다. 수십 개의 파일을 읽고, 수백 번의 검색을 실행하며, 수백만 토큰(Token)을 소비한다. API 청구서를 열 때마다 속이 쓰려온다.

더 까다로운 것은, 이만큼 토큰을 소비했음에도 AI가 "죄송합니다, 찾을 수 없습니다"라고 말하는 경우다. 파일의 바다 속에서 방향 감각을 잃고, 토큰만 사라져 간다.

CodeGraph는 이 문제를 근본적으로 해결한다. 32,100 GitHub Star, MIT 라이선스. AI를 똑똑하게 만드는 것이 아니라, AI에게 코드베이스의 "지도"를 건네주는 접근 방식이다.

• Claude Code, Cursor, Codex 등의 AI 코딩 도구를 일상적으로 사용하는 개발자
• 대규모 프로젝트에서 AI의 토큰(Token) 소비와 API 비용으로 고민하고 있는 분
• 코드베이스 탐색 효율을 높이고, AI 코딩의 ROI를 개선하고 싶은 엔지니어

CodeGraph가 Cursor의 인덱스(Index)와 근본적으로 다른 점은 그 정보 구조다.

Cursor는 벡터 임베딩(Vector Embedding)을 통한 시맨틱 검색(Semantic Search)을 사용한다. 질문을 벡터화하여 코드베이스 내에서 유사도가 높은 단편을 랭킹 형식으로 반환한다. 이는 탐색에는 유용하지만, 결정적인 약점이 있다 —— 구조를 이해하지 못한다. 함수 간의 호출 관계, 모듈 간의 의존 관계, 상속 계층과 같은 정보는 시맨틱 검색으로는 얻을 수 없다. AI는 "관련되어 보이는 단편"을 전달받고, 그것을 단서로 직접 파일을 열어 관계성을 검증해야만 한다.

CodeGraph는 다른 접근 방식을 취한다. tree-sitter를 사용하여 소스 코드를 AST(추상 구문 트리, Abstract Syntax Tree)로 파싱하고, 언어별 추출 규칙을 통해 심볼(함수, 클래스, 메서드, 인터페이스)과 엣지(호출, 임포트, 상속, 구현)를 추출한다.

tree-sitter의 채택은 중요한 설계 결정이다. 원래 GitHub이 Atom 에디터용으로 개발했고, 현재는 Neovim의 핵심 구문 엔진으로 채택된 이 라이브러리는 기존의 컴파일러 프런트엔드와 달리 **내결함성(Fault Tolerance)**이 뛰어나다. 코드에 구문 오류가 있어도 부분적인 AST를 생성할 수 있으며, 해석 속도도 빠르다. 실제 개발 현장에서는 코드가 항상 컴파일 가능한 상태인 것은 아니다 —— 이것이 CodeGraph가 tree-sitter를 선택한 이유다.

추출된 구조 데이터는 모두 로컬 SQLite 데이터베이스에 저장되며, FTS5를 통한 전문 검색(Full-Text Search) 인덱스가 구축된다. AI 에이전트(AI Agent)가 "이 함수를 호출하고 있는 것은?"이라고 물으면, 프로젝트 전체를 탐색하는 것이 아니라 지식 그래프에 대한 쿼리로 응답한다. 단 한 번의 MCP 도구 호출로 엔트리 포인트(Entry Point), 관련 심볼, 코드 스니펫(Code Snippet)이 반환된다.

**Cursor의 시맨틱 검색(Semantic Search)**은 모호한 탐색에는 뛰어나지만, 호출 관계의 확정적인 정보는 얻을 수 없다. AI는 랭킹 결과로부터 직접 파일을 검증해야 한다.

**Gemini Code Assist (구 Google Cloud Code)**는 강력하지만 클라우드 의존적이다. 초대규모 리포지토리(Repository)의 해석이 가능한 반면, 코드가 Google의 서버로 업로드된다. 규제 대상 산업이나 독점적 코드(Proprietary Code)를 다루는 팀에게는 치명적인 제약이 된다.

Sourcegraph는 기능이 풍부하지만 무겁다. 서버 배포, 인덱서(Indexer) 설정, 인프라 유지가 필요하다. CodeGraph는 하나의 바이너리와 SQLite 파일로 완결된다.

**GitHub Copilot의 코드베이스 인덱스(Codebase Index)**는 베타 단계이며, 클라우드 처리만 가능하고 제한적으로 배포되고 있다.

CodeGraph의 차별화 포인트는 **"로컬 + 경량 + 구조 그래프"**의 조합이다. 서버가 필요 없고, 코드 업로드도 필요 없다. 그리고 시맨틱 검색과 같은 모호한 추천이 아니라, 결정적인 호출 관계를 반환한다.

7개 언어 및 7개의 실제 OSS 프로젝트를 대상으로, Claude Opus 4.7 (헤드리스 모드 claude -p)를 사용한 비교 테스트. 동일한 태스크와 동일한 모델을 사용하되, CodeGraph의 유무만을 변수로 하여 4회 실행한 후 중앙값을 보고한다.

주목할 만한 패턴:

프로젝트 규모와 효과가 비례한다. VS Code(약 10,000개 파일)에서는 토큰 (Token)이 280만 → 60.1만으로 급감했다. Excalidraw에서는 350만 → 34.4만으로 줄었다. 파일 수가 많을수록 지도 없는 탐색 비용이 지수 함수적으로 증가한다.

Rust 프로젝트에서 특히 효과가 크다. Tokio에서는 $2.41 → $0.42로 82%의 비용 절감을 기록했다. Rust의 모듈 시스템 (mod, use, pub use, re-export의 다중 계층)은 AI의 탐색을 특히 소모시키는데, CodeGraph가 그 미로를 순식간에 해결한다.

소규모 프로젝트에서는 효과가 제한적이다. OkHttp (Java, 645개 파일)에서는 토큰 (Token) 절감이 13%에 불과했다. Gin (Go, 110개 파일)에서도 34%였다. 프로젝트 규모가 작을 때는 AI가 파일을 직접 읽든 그래프를 참조하든 큰 차이가 나지 않는다.

중요한 점은 이것이 모델의 성능 향상에 따른 결과가 아니라는 것이다. Claude Opus 4.7은 두 테스트 모두에서 동일한 모델이었다. 절감된 토큰 (Token)은 모두 기계적이고 반복적인 파일 탐색에 낭비되었던 것들이다.

Django, Flask, FastAPI, Express, NestJS, Laravel, Rails, Spring, Gin/chi/gorilla/mux, Axum/actix/Rocket, ASP.NET, Vapor, React Router, SvelteKit 등 14개 프레임워크의 라우팅 (Routing) 패턴을 네이티브로 인식한다.

각 프레임워크마다 라우팅 (Routing)을 선언하는 방법이 다르다. Django는 urlpatterns 리스트와 path() 함수, Spring은 @GetMapping 어노테이션 (Annotation), Rails는 get '/x', to: 'users#index' DSL을 사용하는데, CodeGraph는 각각에 특화된 인식 규칙을 구현하고 있다.

"POST /api/users를 처리하는 핸들러는?"라는 질문에 대해, CodeGraph는 URL 패턴으로부터 핸들러 함수를 직접 특정한다. 미들웨어 체인 (Middleware chain), 루트 포함 (Route include), 데코레이터 스택 (Decorator stack)을 한 번에 해결한다. 기존 방식처럼 라우팅 (Routing) 설정 파일을 탐색하고, 뷰 함수를 특정하는 과정을 거치다 중간에 틀려서 되돌아올 필요가 없다.

마이크로서비스나 대규모 API 서피스 (API surface)를 가로지르며 다루는 백엔드 개발자에게는 이 기능 하나만으로도 설치할 가치가 충분하다.

CodeGraph의 인덱스 (Index) 동기화는 3계층 설계로 되어 있어, 수동으로 재구축 (Rebuild)이 필요한 도구들보다 훨씬 사용하기 편리하다.

제1계층: OS 네이티브 파일 워처 (File watcher). macOS FSEvents, Windows ReadDirectoryChangesW, Linux inotify. 각 OS가 제공하는 최하위 계층의 파일 변경 알림 메커니즘이다. 폴링 (Polling)이 없으며 CPU 소비도 없다. 파일을 저장하는 즉시 OS가 CodeGraph에 알림을 보낸다.

제2계층: 디바운스 배칭 (Debounce batching). 2초의 정적 윈도우 (Silence window). 리팩터링 (Refactoring) 시 5개의 파일을 연속으로 저장하더라도, 이들은 1회의 증분 동기화로 묶인다. 파일별 재구축은 발생하지 않는다.

제3계층: Staleness 플래그 + 재연결 시 고속 동기화. 미동기화된 파일은 명시적으로 "Stale"로 표시되어, AI 에이전트 (AI Agent)가 파일을 직접 읽어야 할지 판단할 수 있게 한다. AI 도구가 재연결될 때는 파일 크기와 수정 시간을 빠르게 비교하여 변경된 부분만 동기화한다.

결과적으로, 평소처럼 코드를 작성하기만 하면 인덱스 (Index)는 백그라운드에서 조용히 업데이트된다. "인덱스를 재구축 중이니 잠시 기다려 주십시오"라는 상황은 발생하지 않는다.

지식 그래프 (Knowledge graph)는 .codegraph/codegraph.db라는 단일 SQLite 파일에 저장된다. 클라우드 컴포넌트가 없고, API 키가 필요 없으며, 데이터 전송도 전혀 없다. 독점적 코드(Proprietary code)나 규제 대상 데이터를 다루는 팀에게 이 아키텍처는 도입 장벽을 크게 낮춰준다.

Node.js가 필요 없다. 단 한 개의 명령어로 설치 가능:

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

npm으로도 가능: npx @colbymchenry/codegraph

프로젝트 초기화:

cd your-project
codegraph init -i

-i

플래그로 첫 번째 전체 인덱싱 (Full Indexing)을 실행합니다. 초거대 규모 프로젝트(10만 개 이상의 파일)에서는 첫 실행 시 몇 분에서 10분 이상 소요될 수 있으나, 이는 일회성 비용입니다. 이후에는 증분 동기화 (Incremental Sync)만 수행됩니다.

실용적인 주의 사항:

• macOS: Xcode 커맨드라인 도구(xcode-select --install)를 먼저 설치해야 합니다. 설치되지 않은 경우 호환 모드로 폴백(Fallback)되어 속도가 5~10배 느려집니다.
• 기본 제외 대상: node_modules, vendor, dist, build, target, .venv, .gitignore 항목, 1MB 초과 파일
• 인덱스는 .codegraph/codegraph.db에 집약되어 캐시 파일이 흩어지지 않습니다.
• 지원 AI 도구: Claude Code, Cursor, Codex CLI, OpenCode, Hermes Agent, Gemini CLI, Antigravity, Kiro

초기 인덱싱 시간. 초거대 코드베이스에서는 첫 실행 시 시간이 걸립니다. 이는 tree-sitter의 분석 속도와 디스크 I/O에 따라 달라집니다.

언어 지원의 차이. TypeScript, Python, Rust, Go가 가장 풍부하게 지원됩니다. Objective-C는 "부분 지원"됩니다. 사용 빈도가 낮은 언어에 의존하는 프로젝트라면 사전 테스트를 권장합니다.

탐색의 보조 도구이지 추론의 대체재가 아닙니다. CodeGraph가 절감하는 것은 코드 탐색을 위한 토큰 (Token)이며, 추론 부하가 높은 작업("왜 느린가?", "캐시 전략을 설계해줘")에 직접적으로 기여하지는 않습니다. 어디까지나 AI가 컨텍스트 (Context)를 빠르게 수집하기 위한 도구입니다.

AI 코딩 도구의 진화는 지난 1년간 "더 똑똑한 모델" 개발에 집중되어 왔습니다. Claude vs GPT vs Gemini——각 릴리스가 벤치마크 1위를 다툽니다.

하지만 이러한 도구들이 일상적인 개발 워크플로우에 통합됨에 따라, 또 다른 병목 현상이 부상했습니다. 질문에 답하기 위해 50개의 파일을 읽고, 300만 토큰을 소비하며, 2분 30초가 걸리는 모델은 아무리 똑똑해도 가볍게 사용할 수 없습니다. 마찰이 너무 크고 비용이 너무 눈에 띄기 때문입니다.

더 현명한 접근 방식은 이렇습니다: 적당히 똑똑한 모델에게 정확한 지도를 건네주어, 10개의 파일을 읽고 60만 토큰을 사용하여 1분 만에 답하게 만드는 것입니다.

CodeGraph는 바로 그 지도를 제공합니다.