CodeGraph (codegraph)
codegraph는 모든 심볼, 호출 에지, 의존성을 로컬에 자동 동기화되는 지식 그래프(SQLite)로 구축하고 유지합니다. 초기화가 완료되면 에이전트는 MCP 도구 codegraph_explore를 통해 그래프에서 직접 구조적 질문에 답할 수 있습니다. 단 한 번의 호출로 파일을 전혀 읽지 않고, grep/read 루프를 대체합니다.
사용 시기
- "X는 어떻게 동작하는가?", "X에서 Y로 어떻게 도달하는가?"와 같은 질문에 답하거나 활성 저장소의 낯선 영역을 살펴볼 때
- 함수의 호출자/피호출자 찾기, 호출 경로 추적, 변경의 블래스트 반경 파악
- CodeGraph 백그라운드 데몬 및 환경 프로세스 시작, 관리, 중지
- Git 브랜치, 리베이스, Git 워크트리 전반에 걸친 그래프 인덱스 탐색 및 유지 관리
- 일반적으로 grep하거나 여러 파일을 읽어 수동으로 구조를 재구성해야 하는 모든 질문
아직 .codegraph/ 인덱스가 없는 저장소에는 사용하지 마십시오 (먼저 codegraph init 실행). 또는 로컬에 인덱싱하지 않은 외부/공개 저장소에는 deepwiki 스킬을 사용하십시오.
사전 점검
command -v codegraph || Get-Command codegraph
없는 경우 INSTALL.md를 참조하거나 다음 명령으로 직접 설치하십시오.
# macOS / Linux — Node.js 필요 없음, 자체 런타임 번들 포함
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Windows (PowerShell) — Node.js 필요 없음
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
이것이 대부분의 환경에 필요한 전부입니다. 바로 아래 워크플로 및 시작으로 건너뛰십시오. 번들된 scripts/ (자세한 내용은 INSTALL.md 참조)는 npm 설치 경로 또는 CodeGraph의 Node 라이브러리 API가 특별히 필요한 경우에만 사용하십시오.
워크플로 및 시작
1. 머신당 일회성 설정
CodeGraph를 이 에이전트에 연결합니다 (변경 전 확인):
codegraph install
2. 프로젝트당 최초 설정
활성 프로젝트의 그래프를 구축합니다 (.codegraph/codegraph.db 생성; 전체 초기 인덱스 실행):
cd your-project
codegraph init
3. 일상적인 시작 (작업 시작 시)
작업 전에 수동으로 데몬이나 백그라운드 서비스를 실행할 필요가 없습니다:
- 에이전트 세션 (MCP): AI 호스트 (VS Code Copilot, Claude Code 등)가
codegraph serve --mcp를 통해 MCP 서버를 자동으로 시작합니다. 서버는 필요에 따라 백그라운드 데몬에 연결하거나 생성하며, OS 파일시스템 감시자(filesystem watcher)도 함께 제공합니다. - 상태 확인:
codegraph status를 실행하여 인덱스 상태, 심볼/에지 개수, 보류 중인 동기화 항목을 확인합니다. - 동기화 따라잡기: 에이전트가 닫혀 있는 동안 파일이 변경된 경우 (예: 커밋 풀),
codegraph sync를 실행하여 즉시 빠른 증분 업데이트를 수행합니다.
4. 구조 질의
에이전트는 연결되면 자체적으로 codegraph_explore MCP 도구를 호출합니다. 동일한 기능을 셸에서도 사용할 수 있습니다:
codegraph explore "X에서 Y로 도달하는 방법은?"
codegraph callers someFunction
codegraph callees someFunction
codegraph impact someSymbol
환경 및 데몬 생명주기
CodeGraph는 기본적으로 백그라운드 데몬(데몬 모드)을 실행하여 여러 클라이언트 세션이 단일 감시자, 캐시 및 SQLite 핸들을 공유할 수 있도록 합니다.
데몬 끄기
- 대화형 중지:
codegraph daemon(또는codegraph daemons)을 실행합니다. 프로젝트 데몬을 선택하거나 (맨 위로 올라옴) 모든 데몬을 중지하도록 선택합니다. - 스크립트 / 비대화형 중지: 데몬은 PID를
<project_root>/.codegraph/daemon.pid에 기록합니다. 해당 프로세스 ID를 직접 종료하십시오 (또는~/.codegraph/daemons/<hash>.json을 확인). - 오래된 잠금 정리: 프로세스가 충돌하거나 갑자기 종료된 경우 다음 명령으로 오래된 잠금 및 고아 데몬 아티팩트를 정리합니다:
codegraph unlock
환경 토글 (데몬 및 감시자)
- 직접 모드 (데몬 없음):
CODEGRAPH_NO_DAEMON=1을 설정하여 각 MCP 및 CLI 세션이 공유 데몬에 연결하지 않고 독립적인 자체 포함 프로세스로 실행되도록 강제합니다. - 파일 감시자 비활성화:
CODEGRAPH_NO_WATCH=1을 설정하거나 (--no-watch플래그 사용) 라이브 파일시스템 감시자를 비활성화합니다. 느린 파일시스템 (WSL2/mnt/드라이브, 네트워크 마운트) 또는 배터리 제약 환경에서 권장됩니다.
폐기 / 초기화 해제
- 프로젝트에서 제거:
codegraph uninit을 실행하여.codegraph/인덱스를 삭제하고 Git 동기화 훅을 제거합니다 (--force는 프롬프트를 건너뜁니다). - 머신에서 제거:
codegraph uninstall을 실행합니다 (또는 CLI 바이너리를 유지하려면codegraph uninstall --keep-cli).
Git 브랜치 및 워크트리 작업
Git 브랜치 전환 (단일 작업 트리)
- 파일시스템 기반 동기화: CodeGraph는
git status가 아닌 SQLite의 파일 경로와 콘텐츠 해시를 추적합니다. 브랜치 전환 (git switch <branch>또는git checkout <branch>)은 디스크의 파일을 수정합니다. 파일 감시자가 자동으로 변경 사항을 감지하고 약 2초 이내에 인덱스를 증분 동기화합니다. - 수동 동기화: 체크아웃 중에 감시자가 비활성화되었거나 작동하지 않은 경우
codegraph sync를 실행하여 빠른 증분 따라잡기를 수행합니다. - 대규모 리베이스 / 재구축: 대규모 리베이스 또는 충돌이 많은 브랜치 병합 후에는 다음 명령으로 깨끗한 인덱스 재구축을 강제 실행합니다:
codegraph index --force - Git 동기화 훅 (감시자 꺼짐 시):
CODEGRAPH_NO_WATCH=1이 설정된 경우 CodeGraph는post-commit,post-merge,post-checkout훅을 설치하여 브랜치 전환 후 백그라운드에서 자동으로codegraph sync를 호출할 수 있습니다.
Git 워크트리 및 "인덱스 차용" 위험
- 인덱스 발견: CodeGraph는 현재 작업 디렉터리에서 상위 디렉터리로 올라가며
.codegraph/를 찾습니다. - 위험: Git 워크트리 (예:
git worktree add ../feature-worktree feature)를 사용할 때, 워크트리에 자체.codegraph/디렉터리가 없으면 CodeGraph는 상위로 올라가 메인 체크아웃의.codegraph/인덱스에 바인딩됩니다. 워크트리의 쿼리는 메인 체크아웃 브랜치의 심볼과 소스를 반환하므로 워크트리별 변경 사항이 누락됩니다! - 불일치 감지: CodeGraph는
git rev-parse --show-toplevel을git rev-parse --git-common-dir을 통해 얻은indexRoot와 비교하여detectWorktreeIndexMismatch를 확인합니다. 워크트리가 메인 인덱스를 차용하는 경우 CodeGraph는codegraph status및 MCP 쿼리 도구에서 경고를 표시합니다. - 워크트리의 황금률: 각 워크트리 디렉터리 내에서 항상
codegraph init(또는codegraph init -i)을 실행하십시오. 각 워크트리는 자체 브랜치를 독립적으로 인덱싱하기 위해 고유한 전용.codegraph/디렉터리가 있어야 합니다. - 사용자 지정 디렉터리 격리: 사용자 지정 인덱스 폴더 이름 지정 또는 격리가 필요한 경우 (예: Windows와 WSL2 체크아웃 분리)
CODEGRAPH_DIR을 설정하십시오 (예:export CODEGRAPH_DIR=.codegraph-worktree).
규칙
- 그래프의 결과를 신뢰하십시오. 그래프는 파일 감시자(저장 후 2초 디바운스)를 통해 동기화 상태를 유지합니다. grep으로 다시 확인하지 마십시오.
codegraph_explore가 반환한 소스는 이미 읽은 것으로 간주하고 Read 도구로 동일한 파일을 다시 열지 마십시오..codegraph/인덱스가 있는 프로젝트에 대해서만 쿼리하십시오. 인덱스가 없는 경로는 대신 내장 도구를 사용하라는 깔끔한 안내를 반환합니다. 인덱싱은 의도적인 결정이며 자동화되지 않습니다.- Git 워크트리에서는
codegraph status로 워크트리가 메인 트리의 인덱스를 차용하지 않고 자체 로컬 인덱스를 가지고 있는지 확인하십시오. - 더 좁은 범위의 숨겨진 도구(
codegraph_node,codegraph_search,codegraph_callers,codegraph_callees,codegraph_impact,codegraph_files,codegraph_status)보다codegraph_explore(또는 CLI의codegraph explore)를 선호하십시오. 이러한 도구가 반환하는 모든 것은 이미codegraph_explore에 인라인으로 포함되어 있습니다.
설치 옵션에 대해서는 INSTALL.md를 참조하십시오. 번들된 Node.js 검사기/설치기 스크립트는 scripts/에 있으며, npm 설치 경로 또는 라이브러리 포함에만 필요합니다.