CodeGraph — Claude Code를
똑똑하게 만드는 코드 그래프

먼저, AI가 코드 읽을 때 뭐가 문제인가

Explore 에이전트의 토큰 낭비 구조부터.

Claude Code 같은 AI 코딩 에이전트는 처음 보는 코드베이스를 만나면 일단 탐색(explore)부터 한다. grep으로 키워드를 훑고, glob으로 파일 목록을 뽑고, Read로 한 파일씩 열어본다. 작은 프로젝트라면 괜찮다. 그런데 VS Code나 Swift 컴파일러처럼 파일이 수만 개인 코드베이스가 되면 — 수십 번의 툴 호출과 수십만 토큰이 그 탐색에만 사라진다.

CodeGraph는 이걸 정공법으로 푼다. 코드를 미리 한 번 통째로 분석해서 "함수 A가 함수 B를 부른다" "클래스 X가 인터페이스 Y를 상속한다" 같은 관계망을 SQLite 파일 하나에 저장해 둔다. AI는 grep 대신 그 그래프에 SQL 질의하듯 묻는다. 결과는 평균 툴 호출 58% 감소, 응답 시간 22% 단축, 비용 16% 절감.

이 프로젝트의 핵심 메시지

한 문장으로 줄이면.

TrendShift 10위로 떠오른 이유

벤치마크 + 보안 + 경쟁 비교.

토큰 낭비 문제를 정면으로 풀었다

Claude Code는 코드를 탐색할 때 Explore 에이전트라는 보조 일꾼을 띄워서 grep, glob, Read로 파일을 일일이 읽는다. 큰 프로젝트일수록 이 과정에서 수십 번의 툴 호출과 수십만 토큰이 사라진다. CodeGraph는 이 탐색을 "미리 만들어둔 그래프 1회 질의"로 압축한다.

실제 벤치마크 수치가 압도적

6개의 유명 오픈소스 프로젝트(VS Code, Excalidraw, Alamofire, Swift Compiler 등)에서 Explore 에이전트를 돌려보고 CodeGraph 유/무를 비교했다.

100% 로컬 — 사내 코드에서도 쓸 수 있다

API 키도, 외부 클라우드도, 사내망 밖으로 나가는 데이터도 없다. .codegraph/codegraph.db SQLite 파일 하나가 전부다. 보안이 중요한 회사 코드를 다루는 환경에서 큰 차별점.

경쟁 제품 대비 장점

전체 기술 지도

런타임 · 파싱 · 저장 · 통신 · 빌드.

런타임 / 언어

핵심 의존성

데이터 저장 — SQLite + FTS5

프로젝트 루트의 .codegraph/codegraph.db 파일 하나에 모든 노드/엣지/소스 스니펫이 저장된다. 별도 검색 서버 없이 키워드 검색까지 가능한 이유는 FTS5 가상 테이블을 함께 두기 때문.

통신 — MCP 프로토콜 (stdio)

Claude Code 호스트와 CodeGraph 서버는 표준 입출력(stdio)으로 JSON-RPC를 주고받는다. codegraph serve --mcp가 그 서버 모드. 호스트는 자식 프로세스로 CodeGraph를 띄우고, 표준 입력에 도구 호출 요청을 쓰면 표준 출력으로 결과가 돌아온다. 소켓도 포트도 필요 없다.

파일 감시 — 네이티브 OS 이벤트

폴링이 아니라 네이티브 OS 이벤트를 쓴다 — macOS는 FSEvents, Linux는 inotify, Windows는 ReadDirectoryChangesW. 2초의 debounce(연속 저장을 한 번의 이벤트로 묶기) 후 변경 파일만 증분 재인덱싱한다.

테스트 / 빌드

시스템 구조와 4가지 설계 패턴

전체 구조도 → 핵심 패턴 하나하나.

시스템 구조도

┌──────────────────────────────────────────────────────────────────┐
│                          Claude Code (호스트)                     │
│                                                                  │
│   "Implement user authentication" 같은 사용자 요청                 │
│              │                                                   │
│              ▼                                                   │
│      ┌───────────────┐    ┌───────────────┐                      │
│      │ Explore Agent │ ── │ Explore Agent │  (여러 서브에이전트)  │
│      └───────┬───────┘    └───────┬───────┘                      │
└──────────────┼─────────────────────┼──────────────────────────────┘
               │ stdio (MCP 프로토콜) │
               ▼                     ▼
┌──────────────────────────────────────────────────────────────────┐
│                  CodeGraph MCP 서버 (TypeScript)                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ search   │  │ callers  │  │ context  │  │ impact   │          │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
│       └─────────────┼─────────────┴─────────────┘                │
│                     ▼                                            │
│      ┌──────────────────────────────┐                            │
│      │ SQLite + FTS5 (codegraph.db) │                            │
│      │  · nodes (함수/클래스/메서드)    │                            │
│      │  · edges (calls/extends/imports)│                          │
│      │  · 풀텍스트 인덱스               │                            │
│      └──────────────────────────────┘                            │
│                     ▲                                            │
│                     │ 저장                                        │
│      ┌──────────────┴───────────────┐                            │
│      │   tree-sitter WASM Parser     │  (언어별 query 파일로 추출)   │
│      └───────────────▲──────────────┘                            │
│                      │ 변경 감지                                   │
│      ┌───────────────┴──────────────┐                            │
│      │  Native FS Watcher           │  FSEvents/inotify/Windows  │
│      └──────────────────────────────┘                            │
└──────────────────────────────────────────────────────────────────┘

패턴 1 — Extract → Store → Resolve 3단계 파이프라인

코드를 그래프로 만드는 핵심 흐름.

1. Extract — tree-sitter가 코드를 AST로 만들고, 언어별 query로 함수/클래스 같은 "노드"와 호출/상속 같은 "엣지"를 뽑아낸다
2. Store — 추출 즉시 SQLite에 INSERT. 빠른 검색을 위해 이름 컬럼은 FTS5 가상 테이블에도 같이 들어간다
3. Resolve — 1차로는 "foo() 호출"만 적어두고, 2차 패스에서 그 foo가 실제 어느 파일의 어느 정의인지 매칭. 임포트 추적, 클래스 상속, 프레임워크 패턴(Spring의 @Service 같은)까지 이때 푼다

패턴 2 — 노드/엣지 = SQLite 안에 그래프 DB 흉내내기

전용 그래프 DB(Neo4j 같은 것) 없이도, SQLite의 두 테이블만으로 그래프를 표현한다.

-- 단순화한 스키마
CREATE TABLE nodes (
  id TEXT PRIMARY KEY,
  name TEXT,
  kind TEXT,         -- function/class/method/...
  file TEXT,
  line INTEGER
);
CREATE TABLE edges (
  src TEXT,          -- FROM 노드
  dst TEXT,          -- TO 노드
  kind TEXT          -- calls/extends/imports/...
);
CREATE VIRTUAL TABLE nodes_fts USING fts5(name, content=nodes);

패턴 3 — Incremental Sync (변경 파일만 재인덱싱)

파일이 저장될 때마다 전체를 다시 인덱싱하면 큰 프로젝트에선 비효율적이다. CodeGraph는 변경된 파일과 그 파일을 임포트하는 파일만 다시 처리하는 impact radius 알고리즘을 쓴다. 이건 codegraph_impact 툴로도 노출되어 있어서, "이 함수 바꾸면 뭐가 영향받지?"를 AI가 직접 물어볼 수 있다.

패턴 4 — 시스템 프롬프트로 AI 행동 강제하기

가장 영리한 부분은 코드가 아니라 ~/.claude/CLAUDE.md 주입이다. 인스톨러가 자동으로 다음 규칙을 추가한다.

레포 구조 해부

어디에 뭐가 있는지.

codegraph/
├─ src/                       # 실제 구현체 (TypeScript 94.8%)
│   ├─ bin/                   # CLI 엔트리포인트 (codegraph 명령)
│   ├─ db/
│   │   └─ schema.sql         # SQLite 스키마 정의
│   ├─ extraction/
│   │   └─ wasm/              # tree-sitter 언어별 WASM 파서들
│   ├─ mcp/                   # MCP 서버 구현 (stdio 통신)
│   └─ ...                    # search/callers/context 등 도구 로직
│
├─ __tests__/
│   └─ evaluation/            # 벤치마크/eval 스위트
├─ docs/                      # 사용자 문서
├─ scripts/                   # 설치 후 헬퍼 스크립트
│
├─ BUNDLING.md                 # 번들 런타임 배포 방식 설명
├─ CHANGELOG.md               # 버전별 변경 이력
├─ CLAUDE.md                  # Claude Code에 주입되는 글로벌 지침
├─ TELEMETRY.md               # 텔레메트리 수집 정책 안내
├─ install.sh / install.ps1   # curl/irm 원클릭 인스톨러 스크립트
├─ package.json               # "bin" 필드로 글로벌 명령 등록
└─ vitest.config.ts

분야별 배울 것

이 레포에서 가져갈 5가지 인사이트.

tree-sitter 사용법

MCP 서버 만들기

SQLite + FTS5 활용

시스템 프롬프트로 "에이전트 행동" 조형하기

CLI UX 디자인

시스템 요구사항

최소 → 권장.

직접 해볼 5단계

난이도별 실습 — Easy → Hard.

실습 1 — 내 사이드 프로젝트에 CodeGraph 붙이기Easy

실습 2 — CLI 직접 다뤄보기Easy

실습 3 — Pre-commit hook 만들기Medium

실습 4 — Library 모드로 분석 스크립트 짜기Medium

실습 5 — 새 언어 지원 추가 (PR 도전)Hard

5주 심화 학습 로드맵

주차별로 따라가면 CodeGraph 전체 스택 마스터.

핵심 용어 한눈에

자주 마주칠 단어들.

더 깊이 파고들 자료

공식 · 프로토콜 · 학습 리소스.

공식 자료

• CodeGraph GitHub 레포지토리
• npm 패키지 페이지
• TrendShift 등록 페이지

관련 표준 · 프로토콜

• Model Context Protocol 공식 사이트
• Claude Code 공식 문서
• JSON-RPC 2.0 명세

핵심 라이브러리 · 학습 리소스

• tree-sitter 공식 문서 / AST playground
• SQLite FTS5 공식 문서
• tree-sitter-typescript 레포
• tree-sitter-wasms 패키지