Cranot/roam-code

Local codebase intelligence CLI + MCP server for AI coding agents: SQLite code graph, 28 languages, 287 commands, 246 MCP tools, change-safety gates, audit evidence, zero API keys.

📚 roam‑code 는 무엇인가요

roam‑code 는 코드 에이전트 (LLM 기반 코드 생성 도구)를 위한 Python 기반 로컬 실행 정적 분석 툴킷입니다. 리포지토리의 심볼(함수, 클래스, 임포트, 그들 간의 연결)을 검색 가능한 지도로 구축하여, 에이전트가 "이 함수를 호출하는 것은 누구인가요?" 또는 "이 변경이 영향을 미치는 테스트는 무엇인가요?"와 같은 질문을 모든 파일을 읽지 않고도 할 수 있게 합니다.

이 도구는 원격 모델 호출을 하지 않습니다. 모든 중량 작업은 귀하의 컴퓨터에서 수행됩니다. CLI(roam)로 제공되며, 선택적으로 LLM 기반 에이전트가 표준 도구 호출 인터페이스를 통해 통신할 수 있는 MCP(Model-Control-Protocol) 서버도 제공합니다.

🔧 핵심 기능 (README에 설명됨)

기능	기능 설명	사용 방법
인덱싱 / `roam init`	전체 리포지토리를 분석하고 28개 언어, 287개 명령어, 246개 MCP 도구를 포함하는 심볼 그래프를 구축합니다.	리포지토리 루트에서 `roam init` (또는 가벼운 빌드용 `roam index`)를 실행합니다.
프리플라이트 체크 (`roam preflight <symbol>`)	변경의 폭발 반경 (영향을 받을 수 있는 심볼/파일 수)를 추정하고 관련 테스트, 복잡도, 결합도 등을 보고합니다.	`roam preflight open_db` – 구체적인 수치를 포함한 리스크 평가를 반환합니다.
헬스 요약 (`roam health`)	코드 구조, 발견 사항, 전반적인 "헬스 스코어"에 대한 빠른 개요를 제공합니다.	인덱싱 후 `roam health`를 실행합니다.
검색 (`roam search <name>`)	인덱싱된 그래프 내에서 이름으로 심볼을 찾습니다.	`roam search handleSave`를 실행합니다.
검증 (`roam verify …`)	변경된 파일에 대해 정적 검사를 실행: 이름 규칙, 임포트 유효성, 복잡도, 시크릿 유출, 아이디오마 패턴 경고 등.	`roam verify --auto` (변경된 파일에 적합한 검사를 자동 선택) 또는 더 세밀한 플래그 사용.
MCP 서버 (`roam-code[mcp]`)	네트워크 소켓을 통해 동일한 쿼리를 노출하여 LLM 기반 에이전트가 도구로 호출할 수 있게 합니다.	`pip install "roam-code[mcp]"`로 설치하고 서버를 시작합니다. 에이전트는 MCP를 통해 `roam` 명령어를 호출할 수 있습니다.
Claude Code용 훅 (`roam hooks claude`)	Claude Code 프롬프트에 실행 전 컨텍스트(호출자, 최근 변경 사항)를 자동으로 삽입하고 모델 완료 후 결과를 검증합니다.	`roam hooks claude --write`로 활성화, `--uninstall`로 제거.
Roam Guard	PR 게이트로 작동하여 어떤 검사가 실행되었는지, 그 결과를 기록하고 중요한 발견이 있을 경우 머지 차단할 수 있습니다.	CI에서 `roam verify --auto` 사용; 특정 심각도에서 실패하도록 구성 가능.
성능	인덱싱은 한 번만 비용이 발생하며, 이후 갱신은 빠릅니다. 벤치마크(2026년 5월~7월)에 따르면, 탐색 유형 쿼리에서 LLM의 턴 수가 최대 80% 감소하고 토큰/비용이 크게 감소했습니다.	정확한 수치는 README의 광범위한 벤치마크 표를 참조하세요.

🚀 일반적인 도입 방법

리포지토리에 추가 – 프로젝트의 가상 환경에서 pip install "roam-code[mcp]" 실행.
인덱스 생성 – roam init 실행 (대규모 코드베이스에서는 첫 실행에 수분이 소요될 수 있음).
에이전트 연결 – MCP 서버 또는 Claude 전용 훅을 활성화하여 LLM이 추론 중에 roam 데이터를 요청할 수 있도록 합니다.
CI에서 검사 실행 – roam verify --auto (또는 사용자 지정 검사 세트)를 실행하여 머지 전에 "게이트"를 강제합니다.
반복 – 변경 후 roam preflight <symbol>을 실행하여 커밋 전 잠재적 영향을 확인합니다.

📊 AI 지원 개발에서의 중요성

로컬, 프라이버시 보호 – API 키도, 텔레메트리도 필요 없음; 분석은 온프레미스에서 완료됨.
에이전트 중심 – LLM이 직접 사용할 수 있는 구조화된 심볼 수준의 컨텍스트를 제공하여, 일반적으로 필요한 "검색→파일 열기" 단계를 줄입니다.
언어 독립적 – 28개 프로그래밍 언어를 지원하여 다언어 모노레포에 유용합니다.
게이트 키피팅 – CI 파이프라인의 일부로 위험한 변경 사항의 머지 방지가 가능하며, 인간 코드 리뷰를 보완합니다.

📦 빠른 시작 (4개의 명령어)

pip install "roam-code[mcp]"   # CLI + 선택적 MCP 서버
cd /path/to/your/repo
roam init                       # 인덱스 및 구성 생성
roam health                     # 헬스 스냅샷 확인
roam preflight <symbol>         # 편집 전 리스크 평가

TL;DR

roam‑code 는 코드베이스를 검색 가능한 심볼과 그 관계의 그래프로 변환하는 무료 오픈소스 정적 분석 엔진입니다. LLM 기반 코드 에이전트가 정확하고 저토큰 질문을 할 수 있으며, CI에서 안전 게이트를 강제할 수 있지만, 소스 코드를 기계 외부로 전송하지 않습니다.