도구 호출(tool calls) 94% 감소 · 탐색(exploration) 77% 빨라짐 · 100% 로컬(local)

npx @colbymchenry/codegraph

대화형 설치 프로그램이 Claude Code를 자동으로 설정합니다.

cd your-project
codegraph init -i

Claude Code가 코드베이스를 탐색할 때, grep, glob, Read를 사용하여 파일을 스캔하는 **탐색 에이전트(Explore agents)**를 생성하며, 이는 모든 도구 호출(tool call) 시 토큰을 소비합니다.

CodeGraph는 이러한 에이전트들에게 사전 인덱싱된 지식 그래프(knowledge graph) — 심볼 관계(symbol relationships), 호출 그래프(call graphs), 코드 구조를 제공합니다. 에이전트는 파일을 스캔하는 대신 그래프를 즉시 쿼리(query)합니다.

CodeGraph를 사용했을 때와 사용하지 않았을 때의 Claude Code 탐색 에이전트를 6개의 실제 코드베이스에서 비교 테스트했습니다:

평균: 도구 호출(tool calls) 92% 감소 · 71% 빨라짐

코드베이스 (Codebase)	CodeGraph 사용 시 (With CG)	CodeGraph 미사용 시 (Without CG)	개선 사항 (Improvement)
VS Code · TypeScript	3 calls, 17s	52 calls, 1m 37s	94% 감소 · 82% 빨라짐
Excalidraw · TypeScript	3 calls, 29s	47 calls, 1m 45s	94% 감소 · 72% 빨라짐
Claude Code · Python + Rust	3 calls, 39s	40 calls, 1m 8s	93% 감소 · 43% 빨라짐
Claude Code · Java	1 call, 19s	26 calls, 1m 22s	96% 감소 · 77% 빨라짐
Alamofire · Swift	3 calls, 22s	32 calls, 1m 39s	91% 감소 · 78% 빨라짐
Swift Compiler · Swift/C++	6 calls, 35s	37 calls, 2m 8s	84% 감소 · 73% 빨라짐

전체 벤치마크(benchmark) 상세 정보

모든 테스트는 Claude Code v2.1.91과 Claude Opus 4.6 (1M 컨텍스트)를 사용했습니다. 각 테스트는 동일한 질문을 가진 단일 탐색 에이전트(Explore agent)를 생성했습니다.

사용된 쿼리(Queries):

코드베이스 (Codebase)	쿼리 (Query)
VS Code	"How does the extension host communicate with the main process?"
...

CodeGraph 사용 시 — 에이전트는 codegraph_explore를 사용하고 중단합니다:

코드베이스 (Codebase)	인덱싱된 파일 (Files Indexed)	노드 (Nodes)	도구 사용 (Tool Uses)	토큰 (Tokens)	시간 (Time)	파일 읽기 (File Reads)
VS Code (TypeScript)	4,002	59,377	3	56.6k	17s	0
...

CodeGraph 미사용 시 — 에이전트는 grep, find, ls, Read를 광범위하게 사용합니다:

Codebase	Tool Uses	Tokens	Time	File Reads
VS Code (TypeScript)	52	89.4k	1m 37s	~15
...
주요 관찰 사항 (Key observations):

• CodeGraph를 사용할 때, 에이전트는 파일을 읽는 방식으로 회귀(fallback)하지 않았습니다 — 에이전트는 codegraph_explore 결과를 완전히 신뢰했습니다. CodeGraph가 없으면, 에이전트는 관련 코드를 읽기 시작하기도 전에 탐색(find, ls, grep)에 대부분의 시간을 소비했습니다.
• Java 코드베이스는 전체 질문에 답하기 위해 단 1번의 codegraph_explore 호출만 필요했습니다.
• 교차 언어 쿼리(Python+Rust)가 원활하게 작동했습니다 — CodeGraph의 그래프 순회(graph traversal)가 언어 경계를 넘나드는 연결 고리를 찾아냈습니다.
• Swift 벤치마크(Alamofire)는 Session.request()에서 URLSession.dataTask()까지 **9단계의 호출 체인(call chain)**을 추적했습니다 — CodeGraph의 깊이 3(depth 3) 그래프 순회가 단 한 번의 explore 호출로 전체 체인을 포착했습니다.
• Swift Compiler 벤치마크는 테스트된 가장 큰 코드베이스입니다 (25,874개 파일, 272,898개 노드) — CodeGraph는 이를 4분 미만으로 인덱싱했으며, 에이전트는 6번의 explore 호출과 파일 읽기 0회로 35초 만에 복잡한 횡단적(cross-cutting) 질문에 답했습니다.

스마트 컨텍스트 구축 (Smart Context Building) |
도구 호출 한 번으로 엔트리 포인트(entry points), 관련 심볼(symbols), 코드 스니펫(code snippets)을 반환합니다 — 비용이 많이 드는 탐색 에이전트가 필요 없습니다.
전체 텍스트 검색 (Full-Text Search) |
FTS5를 기반으로 전체 코드베이스에서 이름으로 코드를 즉시 찾습니다.
영향 분석 (Impact Analysis) |
변경을 수행하기 전, 모든 심볼의 호출자(callers), 피호출자(callees) 및 전체 영향 반경(impact radius)을 추적합니다.
항상 최신 상태 유지 (Always Fresh) |
파일 워처(File watcher)가 네이티브 OS 이벤트(FSEvents/inotify/ReadDirectoryChangesW)를 사용하며, 디바운스(debounced)된 자동 동기화를 지원합니다 — 별도의 설정 없이 코딩하는 동안 그래프가 최신 상태로 유지됩니다.
19개 이상의 언어 지원 |
TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Liquid, Pascal/Delphi
프레임워크 인식 라우팅 (Framework-aware Routes) |
13개의 프레임워크에 걸쳐 웹 프레임워크 라우팅 파일을 인식하고 URL 패턴을 핸들러(handlers)와 연결합니다.
100% 로컬 (100% Local) |
데이터가 기기를 떠나지 않습니다. API 키도 필요 없습니다. 외부 서비스도 없습니다. 오직 SQLite 데이터베이스만 사용합니다.

CodeGraph는 웹 프레임워크 (web-framework) 라우팅 파일을 감지하고, references로 연결된 route 노드를 생성하여 해당 핸들러 클래스 (handler classes) 또는 함수 (functions)로 향하는 엣지 (edges)를 출력합니다. 이제 뷰/컨트롤러 (view/controller)의 호출자 (callers)를 쿼리하면 이를 바인딩하는 URL 패턴이 나타납니다.

프레임워크 (Framework)	인식된 형태 (Shapes recognized)
Django	urls.py 내의 path(), re_path(), url(), include() (CBV .as_view(), 점 표기법 경로)
Flask	@app.route('/path', methods=[...]), 블루프린트 (blueprint) 라우트
FastAPI	@app.get(...), @router.post(...), 모든 표준 메서드 (standard methods)
Express	미들웨어 체인 (middleware chains)을 포함한 app.get(...), router.post(...)
Laravel	Route::get(), Route::resource(), Controller@action, 튜플 (tuple) 구문
Rails	get '/x', to: 'users#index', 해시 로켓 (hash-rocket) => 구문
Spring	메서드 상의 @GetMapping, @PostMapping, @RequestMapping
Gin / chi / gorilla / mux	r.GET(...), router.HandleFunc(...)
Axum / actix / Rocket	.route("/x", get(handler))
ASP.NET	액션 메서드 (action methods) 상의 [HttpGet("/x")] 어트리뷰트 (attributes)
Vapor	app.get("x", use: handler)
React Router / SvelteKit	라우트 컴포넌트 (Route component) 노드

npx @colbymchenry/codegraph

설치 프로그램은 다음을 수행합니다:

• codegraph를 전역 (globally)으로 설치할지 확인 (MCP 서버에 필요) - ~/.claude.json에 MCP 서버 설정
• CodeGraph 도구에 대한 자동 허용 (auto-allow) 권한 설정
• ~/.claude/CLAUDE.md에 전역 지침 (global instructions) 추가
• 선택적으로 현재 프로젝트 초기화

MCP 서버를 로드하려면 Claude Code를 재시작하세요.

cd your-project
codegraph init -i

끝입니다! .codegraph/ 디렉토리가 존재하면 Claude Code가 자동으로 CodeGraph 도구를 사용합니다.

수동 설정 (대안)

전역 설치:

npm install -g @colbymchenry/codegraph

~/.claude.json에 추가:

{
"mcpServers": {
"codegraph": {
...

~/.claude/settings.json에 추가 (선택 사항, 자동 허용용):

{
"permissions": {
"allow": [
...

전역 지침 참조 (Global Instructions Reference)

설치 프로그램은 이 지침들을 ~/.claude/CLAUDE.md에 자동으로 추가합니다:

CodeGraph

CodeGraph는 더 빠르고 스마트한 코드 탐색을 위해 코드베이스의 의미론적 지식 그래프 (semantic knowledge graph)를 구축합니다.

프로젝트에 .codegraph/가 존재하는 경우

...

┌─────────────────────────────────────────────────────────────────┐
│ Claude Code │
│ │
...

Extraction (추출)— tree-sitter가 소스 코드를 AST (Abstract Syntax Trees)로 파싱합니다. 언어별 쿼리 (language-specific queries)를 통해 노드 (함수, 클래스, 메서드)와 엣지 (호출, 임포트, 상속, 구현)를 추출합니다. -
Storage (저장)— 모든 데이터는 FTS5 전문 검색 (full-text search) 기능이 포함된 로컬 SQLite 데이터베이스 (.codegraph/codegraph.db)에 저장됩니다. -
Resolution (해결)— 추출 후, 참조 (references)가 해결됩니다: 함수 호출 → 정의, 임포트 → 소스 파일, 클래스 상속, 그리고 프레임워크 특화 패턴 등이 포함됩니다. -
Auto-Sync (자동 동기화)— MCP 서버가 운영체제(OS)의 네이티브 파일 이벤트를 사용하여 프로젝트를 감시합니다. 변경 사항은 디바운스 (debounce, 2초의 유휴 시간) 처리되고, 소스 파일로만 필터링되어 점진적으로 동기화됩니다. 별도의 설정 없이도 코딩하는 동안 그래프가 최신 상태로 유지됩니다.

codegraph # 대화형 설치 프로그램 실행
codegraph install # 설치 프로그램 실행 (명시적)
codegraph init [path] # 프로젝트에서 초기화 (--index를 사용하면 인덱싱도 수행)
...

임포트 의존성 (import dependencies)을 전이적으로 추적하여, 변경된 소스 파일의 영향을 받는 테스트 파일이 무엇인지 찾아냅니다.

codegraph affected src/utils.ts src/api.ts # 인자로 파일 전달
git diff --name-only | codegraph affected --stdin # git diff로부터 파이프(pipe)로 전달
codegraph affected src/auth.ts --filter "e2e/*" # 사용자 정의 테스트 파일 패턴

옵션	설명	기본값
--stdin	stdin으로부터 파일 목록을 읽음	false
-d, --depth <n>	최대 의존성 탐색 깊이	5
-f, --filter <glob>	테스트 파일을 식별하기 위한 사용자 정의 glob 패턴	auto-detect
-j, --json	JSON 형식으로 출력	false
-q, --quiet	파일 경로만 출력	false

CI/hook 예시:

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
...

MCP 서버로 실행될 때, CodeGraph는 다음 도구들을 Claude Code에 노출합니다:

도구	목적
codegraph_search	코드베이스 전체에서 이름으로 심볼 (Symbol) 찾기
codegraph_context	작업을 위한 관련 코드 컨텍스트 (Context) 구축
codegraph_callers	함수를 호출하는 곳 찾기
codegraph_callees	함수가 호출하는 곳 찾기
codegraph_impact	심볼 변경 시 영향을 받는 코드 분석
codegraph_node	특정 심볼에 대한 상세 정보 가져오기 (선택적으로 소스 코드 포함)
codegraph_files	인덱싱된 파일 구조 가져오기 (파일 시스템 스캔보다 빠름)
codegraph_status	인덱스 상태 및 통계 확인

import CodeGraph from '@colbymchenry/codegraph';
const cg = await CodeGraph.init('/path/to/project');
// 또는: const cg = await CodeGraph.open('/path/to/project');
...

.codegraph/config.json 파일은 인덱싱 (Indexing)을 제어합니다:

{
"version": 1,
"languages": ["typescript", "javascript"],
...

옵션	설명	기본값
languages	인덱싱할 언어 (비어 있을 경우 자동 감지)	[]
exclude	무시할 Glob 패턴	["node_modules/**", ...]
frameworks	더 나은 분석을 위한 프레임워크 힌트 (Framework hints)	[]
maxFileSize	이 크기보다 큰 파일은 건너뜀 (바이트 단위)	1048576 (1MB)
extractDocstrings	코드에서 독스트링 (Docstrings) 추출	true
trackCallSites	호출 지점 (Call site) 위치 추적	true

언어 (Language)	확장자 (Extension)	상태 (Status)
TypeScript	.ts , .tsx	전체 지원 (Full support)
JavaScript	.js , .jsx , .mjs	전체 지원 (Full support)
Python	.py	전체 지원 (Full support)
Go	.go	전체 지원 (Full support)
Rust	.rs	전체 지원 (Full support)
Java	.java	전체 지원 (Full support)
C#	.cs	전체 지원 (Full support)
PHP	.php	전체 지원 (Full support)
Ruby	.rb	전체 지원 (Full support)
C	.c , .h	전체 지원 (Full support)
C++	.cpp , .hpp , .cc	전체 지원 (Full support)
Swift	.swift	전체 지원 (Full support)
Kotlin	.kt , .kts	전체 지원 (Full support)
Scala	.scala , .sc	전체 지원 (Full support) (클래스 (classes), 트레이트 (traits), 메서드 (methods), 타입 별칭 (type aliases), Scala 3 열거형 (enums))
Dart	.dart	전체 지원 (Full support)
Svelte	.svelte	전체 지원 (Full support) (스크립트 추출 (script extraction), Svelte 5 runes, SvelteKit 라우트 (routes))
Vue	.vue	전체 지원 (Full support) (script + script-setup 추출, Nuxt page/API/middleware 라우트 (routes))
Liquid	.liquid	전체 지원 (Full support)
Pascal / Delphi	.pas , .dpr , .dpk , .lpr	전체 지원 (Full support) (클래스 (classes), 레코드 (records), 인터페이스 (interfaces), 열거형 (enums), DFM/FMX 폼 파일 (form files))

"CodeGraph not initialized" — 먼저 프로젝트 디렉토리에서 codegraph init을 실행하세요.

Indexing is slow (인덱싱이 느림) — node_modules 및 기타 대규모 디렉토리가 제외되었는지 확인하세요. 출력 오버헤드를 줄이려면 --quiet를 사용하세요.

Indexing is slow / MCP database is locked / WASM fallback active (인덱싱이 느림 / MCP 데이터베이스가 잠김 / WASM 폴백 활성화) — codegraph는 better-sqlite3 (optionalDependencies로 선언된 네이티브 모듈)를 설치할 수 없는 환경을 위해 WASM SQLite 폴백 (fallback)을 제공합니다. 폴백은 네이티브 백엔드보다 5~10배 느리며, 쓰기 작업이 읽기 작업을 차단할 수 있는 저널 모드 (journal mode)를 사용하므로 인덱싱이 실행되는 동안 MCP 쿼리에서 database is locked 오류가 발생할 수 있습니다. codegraph status를 실행하고 Backend: 라인을 확인하세요:

• Backend: native — 빠른 경로를 사용 중이며, 조치할 사항이 없습니다.
• Backend: wasm

— 느린 폴백 (fallback) 경로를 사용 중입니다. 일반적인 원인: C 빌드 도구 누락, 현재 Node 버전용 사전 빌드된 바이너리(prebuilt binary) 없음, 또는 설치 후 Node 버전이 변경됨. 해결 방법:

macOS

xcode-select --install # C 컴파일러 설치

Linux (Debian / Ubuntu)

sudo apt install build-essential python3 make

Linux (RHEL / Fedora)

sudo yum groupinstall "Development Tools"

그 다음 모든 플랫폼에서 다시 빌드:

npm rebuild better-sqlite3

또는 하드 의존성 (hard dep)으로 강제 포함:

npm install better-sqlite3 --save

해결 후에는,

codegraph status 명령어가

Backend: native를

표시해야 합니다.

MCP 서버 연결 안 됨 — 프로젝트가 초기화/인덱싱(indexed) 되었는지 확인하고, MCP 설정의 경로를 검증하며, 커맨드 라인에서 codegraph serve --mcp가 정상 작동하는지 확인하세요.

심볼 (symbols) 누락 — MCP 서버는 저장 시 자동으로 동기화됩니다 (몇 초간 기다려 주세요). 필요한 경우 codegraph sync를 수동으로 실행하세요. 파일의 언어가 지원되는지, 그리고 설정 패턴(config patterns)에 의해 제외되지 않았는지 확인하세요.

MIT