Cranot/roam-code

roam-code는 AI 코딩 에이전트에게 코드베이스에 대한 재사용 가능한 이해를 제공하기 위해 설계된 로컬 코드 분석 툴킷입니다. 프로젝트의 심볼, 연결 및 패턴의 인덱스를 구축하고, 에이전트가 작업 중에 호출할 수 있는 명령 및 MCP 도구로 노출합니다.

주요 기능

• 코드 로컬 인덱싱: 소스를 파싱하고, 함수/클래스를 추출하며, 참조를 해결하고, 모든 내용을 SQLite 데이터베이스에 저장합니다.
• 즉시 사용 가능한 검사 제공 (정적 분석, 패턴 탐지, 영향 분석): 모델 호출이나 클라우드 서비스 없이 로컬 머신에서 실행됩니다.
• 에이전트 통합: MCP (Model Context Protocol) 또는 CLI를 통해 통합되므로, 에이전트는 인덱스를 쿼리하고 코드를 검사하며 분석을 처음부터 다시 구축할 필요 없이 변경 사항을 평가할 수 있습니다.

핵심 명령 ("핵심 5가지")

• roam understand – 프로젝트 개요 및 읽기 시작할 위치 안내.
• roam context <symbol> – 정의와 이를 호출하는 코드 및 호출되는 코드를 표시.
• roam retrieve "<task>" – "로그인 흐름 추적"과 같은 질문에 관련된 코드 검색.
• roam preflight <symbol> – 변경 사항이 미칠 영향(관련 코드, 테스트) 예측.
• roam critique – 놓쳤을 수 있는 관련 코드에 대해 패치 검토 (git diff 파이프 입력).

작동 원리

• 파일을 발견하고, 파싱(tree-sitter 사용)하며, 심볼을 추출하고, 참조를 해결하여 모델을 SQLite에 저장합니다.
• 그래프 분석, Git 기록 및 탐지기 규칙이 다양한 관찰 결과를 제공합니다.
• 정적 검사는 로컬 컴퓨팅만 사용하며, 에이전트의 모델 사용량과는 별개입니다.
• 코드가 변경되면 roam index로 인덱스를 새로 고칩니다.

통합

• MCP를 통해 연결(서버 명령은 roam mcp)하거나 에이전트가 CLI를 직접 호출하게 합니다.
• 8개 프리셋에 걸친 258개의 MCP 도구 (기본 core에는 17개 포함).
• CI 구성(GitHub, GitLab 등)을 생성하고 39개 명령에 대해 SARIF 출력을 생성할 수 있습니다.
• 선택적 Claude Code 훅을 통해 컴파일 타임 컨텍스트 및 편집 후 검증 추가 가능.

개인정보 보호 및 비용

• 완전히 로컬 머신에서 실행되며, 소스, 인덱스 또는 원격 측정 데이터의 자동 업로드가 없습니다.
• 무료 및 오픈소스 (Apache 2.0). 로컬 분석에 API 키가 필요하지 않습니다.
• 유료 계층(PR Replay, Roam Review, Roam Cloud)은 요청 기반이거나 계획 중이며, 무료 CLI는 완전히 기능합니다.

제한 사항

• 정적 분석은 불완전할 수 있으며, 결과는 증명이 아닌 단서입니다.
• LSP, ripgrep 또는 테스트 러너의 대체품이 아니라 보완 도구입니다.
• 추출 깊이는 언어에 따라 다르며, 인식된 파일 확장자가 완전한 의미론적 커버리지를 의미하지는 않습니다.

최적의 사용 사례 에이전트 워크플로우 내의 반복적인 저장소 조사, 구현 선택, 리팩토링 계획 및 변경 사항 검사에 가장 적합합니다.