Muvon/octocode

Structural code intelligence for AI agents — semantic search, knowledge graphs, and a built-in MCP server in one Rust binary. Give Claude, Cursor, and any MCP client a deep understanding of your codebase.

개요

Octocode는 Rust로 작성된 명령줄 도구로, 사용자와 AI 코딩 어시스턴트가 코드베이스를 탐색하는 데 도움을 줍니다. 코드용 검색 엔진이자 파일과 기호(함수, 클래스 등)가 서로 어떻게 연결되는지 보여주는 관계 맵입니다.

이것은 MCP(Model Context Protocol)라는 프로토콜을 사용합니다. 이는 Claude Code, Codex, Cursor, Windsurf와 같은 AI 어시스턴트가 외부 도구에 연결하는 표준 방법입니다. 따라서 Octocode를 실행하고 AI 어시스턴트가 이를 통해 코드베이스를 쿼리하도록 하거나 터미널에서 직접 검색할 수 있습니다.

두 가지 작동 방식

Octocode에는 두 가지 상호 보완적인 메커니즘이 있습니다.

라이브 소스 파싱 — Tree-sitter라는 파서를 사용하여 현재 소스 코드를 직접 읽습니다. 인덱스, 임베딩, AI 모델이 필요 없습니다. 기호와 관계(가져오기, 호출, 상속, 구현)를 즉시 추출합니다. 이를 사용하는 기능: 구조 검색(정의 및 사용처 찾기), 함수 시그니처 보기, 라이브 종속성 그래프.
인덱싱된 의미 검색 — 먼저 octocode index를 실행하여 검색 인덱스를 구축합니다. 코드를 벡터로 임베딩하고(FastEmbed라는 로컬 모델 사용) 키워드도 인덱싱합니다(BM25라는 기술 사용). 검색 시 두 접근 방식을 결합하고 결과를 재순위화합니다. 이를 통해 "의도"로 코드를 찾을 수 있습니다. 예: "authentication middleware"를 입력하면 정확한 단어가 포함되지 않아도 관련 코드가 표시됩니다.

README는 다음과 같이 설명합니다.

현재 소스 → 언어 파서 → 라이브 파일 및 기호 그래프 → MCP 도구
인덱싱된 코드 → 임베딩 + BM25 → 하이브리드 검색 + 재순위화 → CLI / MCP

주요 기능

기능	설명	인덱스 필요 여부
`semantic_search`	의미로 코드, 문서, 인덱스된 기록 검색	예
`structural_search`	현재 소스에서 정의, 사용처, 코드 패턴 검색	아니요
`view_signatures`	전체 파일을 로드하지 않고 함수 시그니처와 가져오기 읽기	아니요
`graphrag`	파일/기호 간의 라이브 관계와 종속성 경로 탐색	아니요(라이브 버전)
`lsp_*` 도구	정의, 참조, 호버 정보, 완성 — 언어 서버 필요(예: `rust-analyzer`)	아니요, 그러나 LSP 서버 필요

설치 및 기본 사용법

다음 중 하나로 설치합니다:

# Linux/macOS/Unix 셸(Windows)
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

# macOS
brew install muvon/tap/octocode

# 또는 소스에서
cargo install octocode  # Rust 1.95+ 및 protoc 필요

그런 다음 Git 저장소 내에서:

cd /path/to/your/project
octocode index
ocotcode search "authentication middleware"

기타 유용한 옵션:

octocode search "auth" "middleware" "session" — 관련 쿼리 결합
octocode search "..." --language rust — 언어별 필터링
octocode search "..." --mode docs — 코드 대신 문서 검색
octocode index --no-git — Git 저장소가 아닌 디렉토리용
octocode watch — 파일 변경 시 인덱스 업데이트(MCP 서버와 별도로 실행)
octocode graphrag overview — 인덱스된 GraphRAG 활성화 후(의미 기반 파일 검색 및 선택적 LLM 생성 설명을 갖춘 선택적 영구 레이어)

기본적으로 API 키가 필요 없습니다. 임베딩 및 재순위화 모델은 처음 사용 시 로컬에 다운로드됩니다. 원격 공급자(임베딩, 재순위화, LLM)는 선택 사항이며 구성할 수 있습니다.

AI 어시스턴트 연결

Claude Code: claude mcp add --transport stdio octocode -- octocode mcp --path /path/to/your/project

Codex CLI: codex mcp add octocode -- octocode mcp --path /path/to/your/project

Claude Desktop, Cursor, Windsurf: 클라이언트의 MCP 구성에 command: "octocode", args: ["mcp", "--path", "/path/to/your/project"]를 사용하는 JSON 항목을 추가합니다.

LSP(언어 서버) 도구 활성화: octocode mcp --path /path/to/your/project --with-lsp rust-analyzer

기본적으로 MCP 서버는 다시 인덱싱하지 않습니다. 코드 변경 후 octocode index를 다시 실행하거나 별도 프로세스에서 octocode watch를 실행합니다.

OctoFS 통합

OctoFS는 AI 어시스턴트에게 파일 읽기 및 원자적 편집 기능을 제공하는 동반 도구입니다. Octocode는 이와 함께 작동합니다: structural_search는 N:hh|content 형식의 소스 줄을 반환합니다. 여기서 N:hh는 줄 ID(들여쓰기를 포함한 원래 줄의 해시)입니다. OctoFS의 view 및 batch_edit는 동일한 ID를 사용하므로 에이전트는 편집 대상을 찾기 위해 줄을 다시 읽을 필요 없이 검색한 다음 편집할 수 있습니다. OctoFS는 편집을 적용하기 전에 ID를 검증하고 내용이 변경된 경우 오래된 대상을 표시합니다. N:hh| 접두사는 메타데이터이며 코드의 일부가 아닙니다. OctoFS는 선택 사항입니다. Octocode는 단독으로 작동합니다.

README에는 Octomind도 언급되어 있습니다. 이는 동반 AI 에이전트 런타임으로, developer:general 에이전트는 Octocode 및 OctoFS 기능을 번들로 포함합니다.

지원 언어

Rust, Python, TypeScript/JavaScript(.ts, .tsx, .js, .jsx), Go, PHP, C/C++(많은 확장자), Ruby, Elixir, Java, Swift, Svelte, Lua, CSS/SCSS/Sass, JSON, Bash, Markdown.

개인정보 보호 및 구성 하이라이트

기본적으로 로컬 모델 — 임베딩 및 재순위화는 모델 다운로드 후 로컬에서 실행됩니다. API 키가 필요 없습니다.
로컬 저장소 — 인덱스는 저장소 외부의 Octocode의 프로젝트별 데이터 디렉토리에 저장됩니다.
파일 제외 — .gitignore 및 .noindex를 존중하며 추가 제외를 구성할 수 있습니다.
클라이언트 주의 사항 — 로컬 모델을 사용하더라도 Octocode를 사용하는 AI 어시스턴트는 도구에서 반환된 소스 콘텐츠를 받을 수 있습니다.
원격 공급자 선택 사항 — 활성화하면 해당 기능에 필요한 쿼리 및 소스 콘텐츠를 받습니다. API 키는 환경 변수에 넣습니다.

성능 벤치마크

README에는 과거 벤치마크 결과(2026년 6월 21일 날짜, Octocode 0.17.1 사용 — 현재 릴리스가 아님)가 포함되어 있습니다. 127개의 코드 검색 쿼리에서 재순위화를 비활성화한 상태:

구성	Hit@5	Hit@10	MRR	NDCG@10	Recall@10
밀집 벡터만	0.598	0.717	0.485	0.528	0.671
하이브리드 0.7/0.3(벡터/키워드)	0.598	0.717	0.485	0.528	0.671
하이브리드 0.3/0.7	0.732	0.835	0.572	0.620	0.807

핵심: 키워드 검색 가중치를 높이면 해당 과거 테스트에서 결과가 개선되었습니다. README는 이러한 수치가 현재 릴리스를 측정하지 않는다고 명시적으로 경고합니다.

결론

Octocode는 AI 어시스턴트에게 코드베이스의 구조화되고 검색 가능한 보기를 제공하는 개발자 도구입니다. 의미 검색, 정확한 구조 검색, 라이브 기호/종속성 그래프를 결합하고 기본적으로 로컬에서 실행되며 다양한 언어를 지원합니다.

라이선스 및 기여

Apache License 2.0, Muvon이 유지 관리합니다. GitHub Issues, Discussions 또는 이메일(opensource@muvon.io)을 통해 기여할 수 있습니다.

위의 모든 사실은 프로젝트 README에서 직접 가져온 것입니다.