본문 바로가기
AI 생성 글 정리/tech_github

CodeGraph — AI 코딩 에이전트를 위한 로컬 코드 지식 그래프

by Honbul 2026. 5. 27.

CodeGraph는 Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro 같은 AI 코딩 에이전트가 매번 grep, glob, Read로 저장소를 재탐색하지 않도록, 코드베이스를 미리 파싱해 로컬 지식 그래프로 만드는 오픈소스 프로젝트다.

핵심 아이디어는 단순하다. 소스 파일을 tree-sitter로 AST 파싱하고, 함수·클래스·타입·라우트 같은 심볼과 호출·임포트·상속·참조 관계를 SQLite 그래프에 저장한 뒤, MCP 서버/CLI/TypeScript API로 에이전트가 즉시 질의하게 만든다.

 

분석 기준일: 2026-05-27 KST
대상 저장소: https://github.com/colbymchenry/codegraph
패키지: @colbymchenry/codegraph
현재 확인된 패키지 버전: 0.9.6

Quick Links

구분 링크 메모
GitHub Repository https://github.com/colbymchenry/codegraph README, 소스, 릴리스, docs 디렉터리
공식 문서 https://colbymchenry.github.io/codegraph/ Getting Started, Core Concepts, Reference
Quickstart https://colbymchenry.github.io/codegraph/getting-started/quickstart/ 설치 및 codegraph init -i
MCP Server Reference https://colbymchenry.github.io/codegraph/reference/mcp-server/ MCP 도구 목록과 에이전트 사용 방식
CLI Reference https://colbymchenry.github.io/codegraph/reference/cli/ query, context, impact, serve --mcp 등
npm Package https://www.npmjs.com/package/@colbymchenry/codegraph 전역 설치 또는 npx 실행
Design Docs https://github.com/colbymchenry/codegraph/tree/main/docs/design 동적 디스패치, iOS/RN 브리징 등 설계 문서
Demo README 내 codegraph init -i 실행 GIF GitHub user-attachments 기반 이미지. 이 아카이브에는 실행 환경 제약 때문에 재구성 터미널 이미지를 포함했다.
Paper 확인된 프로젝트 공식 논문 없음 이름이 같은 별도 연구 논문과 혼동 주의

이미지/자산 매핑

아카이브 이미지 본문 위치 설명
figures/기능_도구_맵.png Key Features MCP/CLI 도구가 어떤 질문을 해결하는지 요약
figures/벤치마크_요약.png Key Features README/공식 문서가 보고한 비용·토큰·속도·툴콜 감소치 시각화
figures/데이터베이스_스키마.png Key Features / Architecture schema.sql 기반 로컬 그래프 저장 구조
figures/동적_디스패치_브리징.png Key Features callback, observer, route, mobile bridge 같은 정적 분석 사각지대 보강 흐름
figures/언어지원_스택.png Tech Stack 지원 언어와 런타임 스택 요약
figures/아키텍처_파이프라인.png Architecture README/공식 문서/소스 구조를 통합한 시스템 파이프라인
figures/설치_초기화_터미널.png Usage & Setup README의 init 데모 GIF 맥락을 바탕으로 재구성한 설치·초기화 예시

원본 이미지 수집 메모: README에는 codegraph init -i를 보여주는 GitHub user-attachments 이미지가 확인되었다.
다만 이 실행 환경에서는 GitHub/S3 서명 이미지 바이너리를 직접 저장할 수 없어, 문서·README 명령과 기능 설명을 기준으로 재구성한 PNG를 figures/에 포함했다.
아키텍처 다이어그램은 README의 ASCII 구조, 공식 문서의 4단계 처리 흐름, CLAUDE.md/소스 디렉터리 분석을 바탕으로 제작했다.

Key Features

1. AI 에이전트용 사전 색인 그래프

CodeGraph의 문제의식은 “AI 코딩 에이전트가 같은 코드베이스를 매 세션 다시 훑는다”는 데 있다.

Claude Code나 Cursor 같은 에이전트가 구조 질문을 받을 때, 보통 파일 탐색 → grep → 파일 읽기 → 관련 심볼 재탐색을 반복한다. CodeGraph는 이 탐색 단계를 로컬 그래프 질의로 대체한다.

에이전트는 codegraph_context, codegraph_trace, codegraph_impact 같은 도구로 이미 계산된 관계를 가져오고, 필요한 경우에만 원본 코드를 읽는다.

그림: CodeGraph의 주요 질의 도구. search는 심볼 검색, context는 작업 단위 코드 맥락 조합, trace는 두 심볼 사이의 호출 경로 추적, impact는 변경 영향 반경 분석에 초점을 둔다.

2. 비용·토큰·툴 호출 절감 지향

공식 문서와 README는 7개 실제 오픈소스 코드베이스에서 각 arm의 중앙값 4회 실행 기준으로, CodeGraph를 제공했을 때 평균적으로 비용 35% 절감, 토큰 57% 감소, 탐색 속도 46% 향상, 툴 호출 71% 감소를 보고한다.

이 수치는 프로젝트 제공 벤치마크이므로 독립 검증값으로 보기는 어렵지만, 구조적으로는 타당한 방향성을 가진다.

“탐색”을 반복 질의에서 사전 색인 조회로 바꾸면, 대규모 코드베이스일수록 에이전트의 파일 I/O와 컨텍스트 소비가 줄어들 가능성이 크다.

그림: 프로젝트가 보고한 평균 개선 수치. 운영 도입 전에는 조직의 실제 저장소, 에이전트, 프롬프트, MCP 설정 조건에서 재측정하는 것이 안전하다.

3. tree-sitter 기반 결정론적 추출

CodeGraph는 LLM이 코드를 요약해서 그래프를 만드는 방식이 아니다.

소스 파일을 tree-sitter로 AST 파싱하고, 언어별 extractor가 함수, 클래스, 메서드, 타입, 컴포넌트, 라우트 등의 노드와 호출, 임포트, 상속, 구현, 참조 등의 엣지를 추출한다.

이 구조는 “요약의 그럴듯함”보다 “구문 구조에서 나온 반복 가능한 사실”을 우선한다.

 

이 접근은 의료 AI나 생물정보학 파이프라인처럼 코드 변경의 재현성과 추적성이 중요한 영역에서 의미가 있다.

예를 들어 전처리 함수 하나가 모델 입력, 평가 스크립트, 테스트에 어디까지 영향을 주는지 볼 때, 자연어 요약보다 호출 그래프와 파일 관계가 더 감사 가능하다.

4. 100% 로컬 저장과 FTS5 검색

그래프 데이터는 프로젝트 내부의 .codegraph/codegraph.db에 저장된다.

스키마는 nodes, edges, files, unresolved_refs, nodes_fts를 중심으로 구성된다.

nodes는 심볼, edges는 심볼 간 관계, files는 파일 색인 상태, nodes_fts는 심볼명·시그니처·콘텐츠 검색을 담당한다.

공식 문서가 강조하듯 API 키나 외부 서비스가 필요하지 않고, 데이터는 로컬에 남는다.

그림: src/db/schema.sql에서 확인되는 핵심 테이블을 개념적으로 재구성한 스키마.
edges는 nodes 사이의 호출·임포트·상속·참조 관계를 저장하고, nodes_fts는 빠른 심볼 검색을 담당한다.

5. MCP 서버, CLI, TypeScript 라이브러리의 동일 그래프 공유

CodeGraph는 단일 CLI 도구에 그치지 않는다.

MCP 서버로 에이전트에 연결되고, CLI로 직접 질의할 수 있으며, TypeScript 라이브러리로 애플리케이션 안에서 사용할 수 있다. 이 구조의 장점은 동일한 인덱스를 여러 소비자가 공유할 수 있다는 점이다.

개발자는 터미널에서 codegraph impact AuthMiddleware를 실행하고, 에이전트는 같은 그래프를 MCP로 질의한다.

특히 최근 릴리스 흐름에서는 프로젝트별 공유 MCP daemon이 강조된다.

여러 AI 에이전트가 같은 프로젝트에서 동시에 접근할 때, 파일 watcher와 SQLite 연결, tree-sitter 준비 비용을 각 세션마다 중복하지 않고 공유하는 방향이다.

6. 자동 동기화와 파일 watcher

MCP 서버는 프로젝트 파일 변화를 감지해 그래프를 최신 상태로 유지한다.

공식 문서에 따르면 FSEvents, inotify, ReadDirectoryChangesW 같은 네이티브 OS 이벤트를 사용하고, 변경은 debounce와 source-file filter를 거쳐 incremental sync로 반영된다.

즉, codegraph init -i로 한 번 인덱스를 만든 뒤 개발 중 변경이 생기면 전체 재색인 대신 필요한 부분을 동기화하는 흐름이다.

7. 프레임워크 라우트와 동적 디스패치 보강

정적 AST 파싱만으로는 callback 등록, EventEmitter 채널, React re-render, JSX child, Django ORM descriptor, route handler 같은 동적 연결을 완전히 복원하기 어렵다.

CodeGraph는 이런 경계에서 heuristic edge를 합성하고, 해당 엣지에 provenance를 표시한다.

에이전트는 “이 연결은 AST에서 직접 나온 사실인지, resolver가 합성한 추정 엣지인지”를 함께 볼 수 있다.

그림: 이벤트 emitter, route binding, Swift/ObjC ↔ React Native/Expo 같은 연결은 단순 호출 엣지로 나타나지 않을 수 있다. CodeGraph는 resolver와 synthesizer로 흐름을 연결하고, 합성 엣지는 heuristic provenance로 구분한다.

8. 다언어 코드베이스 지원

공식 문서는 TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C/C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Liquid, Pascal/Delphi, Lua, Luau 등을 자동 확장자 기반으로 지원한다고 설명한다.

GitHub 저장소의 구현 언어 비중은 TypeScript가 대부분이며, 패키지 구조도 TypeScript library + CLI + MCP server에 맞춰져 있다.

Tech Stack

그림: 공식 문서의 언어 지원 표와 package.json 의존성을 기준으로 요약한 기술 스택.

영역 확인 내용
패키지 @colbymchenry/codegraph
확인 버전 0.9.6
런타임 요구사항 Node.js >=20.0.0 <25.0.0
주 언어 TypeScript 중심. GitHub 언어 통계 기준 TypeScript 비중이 압도적이다.
빌드 tsc, asset copy, CLI chmod 처리
테스트 Vitest ^2.1.9
파서 web-tree-sitter ^0.25.3, tree-sitter-wasms ^0.1.11
저장소 SQLite DB, FTS5 virtual table, local .codegraph/codegraph.db
CLI commander ^14.0.2, @clack/prompts ^1.3.0
파일 감시/매칭 chokidar ^4.0.3, picomatch ^4.0.3, ignore ^7.0.5
설정 파싱 jsonc-parser ^3.3.1
배포 형태 npm package, one-command install script, bundled runtime 방향

 

소스 구조는 다음처럼 역할이 분리되어 있다.

src/
  bin/          CLI entrypoint and Node version/runtime checks
  context/      agent-consumable markdown/JSON context builder
  db/           schema.sql, SQLite access, migrations/query layer
  extraction/   tree-sitter grammars, language extractors, WASM parser runtime
  graph/        graph traversal, callers/callees/impact/query manager
  installer/    agent instruction/config installer
  mcp/          daemon, server, session, transport, MCP tools
  resolution/   import/name/framework/dynamic-dispatch resolution
  search/       symbol and text search helpers
  sync/         file watcher and incremental sync
  ui/           terminal UI helpers

Architecture

그림: CodeGraph의 전체 처리 흐름.
AI 에이전트는 MCP 서버/CLI/API를 통해 질의하고, 프로젝트별 daemon은 파일 감시와 질의를 조정한다.
extractor는 tree-sitter로 그래프 원재료를 만들고, resolver는 임포트·이름·프레임워크·동적 디스패치 경계를 보강한다.

 

CodeGraph의 아키텍처는 크게 네 단계로 볼 수 있다.

  1. Extraction
    파일을 tree-sitter AST로 파싱하고, 언어별 extractor가 노드와 엣지를 추출한다.
    여기서 생성되는 노드는 함수, 클래스, 타입, 모듈, 라우트, 컴포넌트 같은 코드 단위이고, 엣지는 호출, 임포트, 상속, 구현, 참조 같은 관계다.
  2. Storage
    추출 결과는 .codegraph/codegraph.db에 저장된다.
    FTS5 인덱스는 심볼명과 시그니처 검색을 빠르게 하고, 파일 해시와 수정 시각은 incremental sync 판단에 사용된다.
  3. Resolution
    raw edge는 충분하지 않다. foo()라는 호출이 실제 어떤 파일의 어떤 함수인지, import alias가 어떤 모듈을 가리키는지, framework route가 어떤 controller에 연결되는지, EventEmitter 채널이 어떤 callback으로 이어지는지 해석해야 한다.
    이 레이어가 CodeGraph의 실용성을 좌우한다.
  4. Graph Query / Context Building
    최종적으로 agent-facing 도구가 호출된다.
    search는 심볼 탐색, callers와 callees는 1-hop 관계, impact는 변경 영향 반경, trace는 두 심볼 사이의 경로, context는 작업 목적에 맞는 코드 맥락 묶음을 만든다.

내부 구성의 핵심 포인트

  • ExtractionOrchestrator: 프로젝트 파일을 순회하고 언어별 extractor를 실행한다.
  • ReferenceResolver: 임포트, 호출, 상속, 이름 매칭, 프레임워크 패턴을 실제 노드 관계로 변환한다.
  • GraphQueryManager / GraphTraverser: callers, callees, impact, trace 같은 그래프 탐색을 담당한다.
  • ContextBuilder: 에이전트가 바로 사용할 수 있는 Markdown/JSON 컨텍스트를 구성한다.
  • MCPServer / daemon: Claude Code, Cursor, Codex CLI 등 외부 에이전트와의 연결 지점을 제공한다.

Usage & Setup

공식 quickstart 기준으로 설치와 초기화는 다음 흐름이다.

# macOS / Linux: Node.js 없이 install script 사용
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

# Node.js가 있다면 npm/npx 사용
npx @colbymchenry/codegraph
npm i -g @colbymchenry/codegraph

# 프로젝트 초기화
cd your-project
codegraph init -i

 

CodeGraph 설치와 초기화 터미널 예시

그림: README의 init 데모 맥락을 바탕으로 재구성한 설치·초기화 예시. 실제 출력은 버전과 선택한 agent 설정에 따라 달라질 수 있다.

 

자주 쓰는 CLI 명령은 다음과 같다.

codegraph                         # interactive installer
codegraph install                 # agent 설정 설치
codegraph uninstall               # agent 설정 제거
codegraph init [path]             # 프로젝트 초기화
codegraph index [path]            # 전체 색인
codegraph sync [path]             # incremental update
codegraph status [path]           # 그래프 상태 확인
codegraph query <search>          # 심볼 검색
codegraph files [path]            # 색인된 파일 구조 조회
codegraph context <task>          # 작업용 AI 컨텍스트 구성
codegraph callers <symbol>        # 특정 심볼 호출자 조회
codegraph callees <symbol>        # 특정 심볼이 호출하는 대상 조회
codegraph impact <symbol>         # 변경 영향 분석
codegraph affected [files...]     # 변경 파일이 영향 주는 테스트 추적
codegraph serve --mcp             # MCP 서버 실행

 

MCP를 직접 실행할 때는 다음 명령을 사용한다.

codegraph serve --mcp

 

설치 프로그램이 agent 설정을 자동 구성하면, .codegraph/ 인덱스가 존재하는 프로젝트에서 에이전트가 CodeGraph 도구를 자동으로 사용한다.

Personal Insights

의료 AI 관점

의료 AI 코드베이스는 데이터 전처리, feature engineering, 모델 추론, calibration, evaluation, regulatory reporting이 여러 모듈에 걸쳐 얽히는 경우가 많다.

CodeGraph의 impact와 trace는 “이 normalization 함수를 바꾸면 어떤 inference path와 validation script가 영향을 받는가” 같은 질문에 유용하다.

또한 100% 로컬 구조는 민감한 의료 코드나 내부 파이프라인을 외부 서비스로 보내지 않는다는 점에서 보안 설계와 잘 맞는다.

다만 CodeGraph가 의료 규제 준수를 자동으로 보장하지는 않는다.

PHI/PII가 코드 주석, fixture, 테스트 데이터에 포함되어 있다면 로컬 DB에도 그대로 색인될 수 있다.

의료 조직에서 도입할 때는 .codegraph/의 접근 권한, 백업 정책, 로그 수집 여부, 민감 fixture 제외 규칙을 별도로 설계해야 한다.

Bioinformatics 관점

생물정보학 프로젝트는 Python, Rust, Go, JavaScript, Shell, workflow tool이 혼재하는 경우가 많다.

CodeGraph가 Python, Rust, Go, JavaScript 등을 지원한다는 점은 장점이지만, R, Nextflow, Snakemake, WDL, CWL 같은 워크플로 언어는 현재 핵심 지원 목록에 명시되어 있지 않다.

따라서 유전체 분석 파이프라인 전체를 추적하려면 “지원 언어로 작성된 라이브러리 코드”와 “워크플로 정의 파일” 사이의 경계가 남을 수 있다.

그래도 library layer의 영향 분석에는 실용성이 높다.

예를 들어 variant calling 파이프라인에서 parse_vcf, normalize_sample_id, filter_low_quality_reads 같은 함수가 downstream QC나 리포트 생성에 어떻게 연결되는지 빠르게 파악할 수 있다.

향후 Snakemake/Nextflow extractor가 추가된다면 생물정보학 영역에서 가치가 더 커질 가능성이 있다.

Autonomous Agent 개발 관점

자율 에이전트가 코드 수정 작업을 수행할 때 가장 큰 비용은 “어디를 봐야 하는지 찾는 탐색 비용”이다.

CodeGraph는 이 탐색을 구조화된 graph query로 바꿔준다. 특히 trace와 context는 agentic workflow에서 중요한 primitive다.

에이전트는 먼저 관련 심볼과 호출 경로를 좁히고, 그 다음에만 파일을 읽고 patch를 제안할 수 있다.

동적 디스패치와 heuristic provenance 표시는 agent safety 측면에서도 중요하다.

에이전트가 “이 호출 경로는 확실한 AST edge”와 “resolver가 합성한 edge”를 구분할 수 있으면, 확신 수준이 낮은 연결에 대해 추가 검증을 수행할 수 있다.

이는 autonomous patch generation에서 잘못된 코드 경로를 따라 수정하는 위험을 줄이는 데 도움이 된다.

기술적 한계와 개선 여지

  • 프로젝트 제공 benchmark는 유용한 방향성을 보여주지만, 조직별 저장소에서 독립 재현이 필요하다.
  • 다언어 지원 범위는 넓지만, 모든 언어·프레임워크의 semantic resolution 품질이 동일하다고 가정해서는 안 된다.
  • heuristic edge는 강력하지만 false positive/false negative 가능성이 있다. provenance 표시를 agent prompt와 UI에서 명확히 활용해야 한다.
  • .codegraph/ DB가 커질 때의 성능, cleanup, CI cache 전략은 대규모 monorepo에서 별도 검증해야 한다.
  • Notebook, R, workflow DSL 중심의 연구 코드베이스에서는 extractor coverage가 제한될 수 있다.

Source Notes

분석에 사용한 공개 자료는 다음과 같다.

공개 Wiki와 Discussions는 별도 분석 가능한 콘텐츠가 확인되지 않았다. /wiki 접근은 저장소 홈으로 리다이렉트되었고, Discussions 전용 공개 결과도 확인 가능한 문서 근거로 확보되지 않았다. 따라서 본 리포트는 README, 공식 문서, package metadata, 소스 구조, schema, design docs를 중심으로 작성했다.

'AI 생성 글 정리 > tech_github' 카테고리의 다른 글

llmfit — 로컬 하드웨어에서 “실제로 잘 도는” LLM을 찾아주는 Rust 기반 모델 피팅 도구  (0) 2026.05.27
K9s: Kubernetes 운영을 터미널에서 빠르게 탐색·관찰·조작하는 TUI  (0) 2026.05.27
Beszel — 가벼운 self-hosted 서버 모니터링 허브와 에이전트  (0) 2026.05.27
SmallCode — 소형 로컬 LLM을 실전 코딩 에이전트로 끌어올리는 터미널 네이티브 에이전트  (0) 2026.05.27
AnythingLLM — 문서 RAG, AI Agent, 모델 라우팅을 하나로 묶은 프라이버시 우선 AI 워크스페이스  (0) 2026.05.27

관련글

티스토리툴바