AI 코딩 도구를 사용하면 자주 경험하는 문제는 "프로젝트 구조를 파악하는 데 시간이 많이 걸린다" 였다. 특히 멀티 모듈이나 대규모 코드로 구성된 프로젝트의 경우 기존 소스를 검색하여 파악하는데 많은 시간이 걸린다.
CodeGraph 는 소스 코드를 분석해서 코드베이스를 그래프 형태로 인덱싱하는 오픈소스 프로젝트이다.
CodeGraph는 AI 코딩 에이전트가 프로젝트 소스코드를 매번 grep, find, Read로 처음부터 탐색하지 않도록, 코드베이스를 미리 인덱싱해 코드 지식 그래프로 제공하는 도구다. 로컬 코드베이스를 분석해 .codegraph/ 디렉터리에 인덱스를 저장하고, Codex CLI, Claude Code, Cursor, Gemini CLI, Antigravity IDE 같은 AI 에이전트가 MCP를 통해 이 그래프를 조회할 수 있도록 해준다. 공식 설명에서도 CodeGraph는 tree-sitter 기반으로 코드베이스를 파싱하고, 심볼·엣지·파일 정보를 SQLite/FTS5에 저장하며, MCP를 통해 AI 에이전트에 제공하는 로컬 우선 코드 인텔리전스 도구라고 설명한다.
CodeGraph는 이런 품질 이슈를 “자동 정답화”로 해결하지 않고, AST 기반 그래프 + context/trace/impact + 원본 body 제공으로 사실 확인 비용을 줄이는 방식으로 완화하고 있다.
1. 설치하기
환경
- Model : MacBook Pro (14-inch, 2021)
- CPU : Apple M1 Pro
- MENORY : 16GB
- DISK : 512 GB SSD
- OS : macOS 15.3.1 (24D70)
- AI Coding Agent : Codex
설치는 npm 을 사용하여 전역으로 설치하는 방식을 사용했다. (여러 프로젝트에서 사용할 수 있도록)
npm install -g @colbymchenry/codegraph
설치 이후에는 다음 명령으로 확인 할 수 있다.
codegraph --version
which codegraph
2. AI 코딩 에이전트에 MCP 연결
CodeGraph는 MCP 서버로 동작한다. 따라서 Codex, Claude Code, Cursor 같은 AI 코딩 도구에서 사용하려면 먼저 MCP 설정을 연결해야 한다. Codex 를 주력으로 사용하고 있어 Codex 에 MCP 로 등록했다.
codegraph install
이 명령은 현재 개발환경에 설치된 AI 에이전트를 감지하고, CodeGraph MCP 서버 설정을 자동으로 추가한다. 공식 README 기준으로 자동 설정 대상에는 Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro 등이 포함된다.
기본적으로 설치는 전역으로 설치하고 각 프로젝트 경로에서 초기화를 해주것이 좋다. (여러 프로젝트에서 사용할 수 있게)
성공적으로 연결되었다면 아래와 같이 확인하거나 codex 도구에서 /mcp 명령으로 확인 할 수 있다.
grep -A 3 -B 1 "codegraph" ~/.codex/config.toml
Codex 앱에서 /mcp 입력
2. 로컬 프로젝트 초기화 및 인덱스 생성
로컬 프로젝트 루트로 이동하여 init 명령을 사용하여 초기화를 실행 합니다. 최초 초기화인 경우 -i 옵션을 사용하여 코드 분석 인덱싱까지 함께 진행하는 것이 일반적이다.
codegraph init -i
코드가 추가 되거나 수정되면 index 명령을 사용하여 인덱스를 갱신한다.
codegraph index
status 명령으로 초기화 또는 인덱싱 상태를 확인할 수 있다.
codegraph status














































