Eulix가 대형 코드 저장소를 로컬에서 검색하고 호출 관계를 보여준다

Eulix는 저장소의 기호와 호출 그래프를 색인해 질의 가능한 형태로 만들고, 질문에 답할 수 있는 가장 간단한 경로를 선택하는 오픈소스 도구다. 대부분의 질문은 저장소에서 생성한 데이터만으로 처리하며, 추론이 필요한 경우에만 선택적으로 대규모 언어 모델(LLM)을 사용한다.

빠른 시작은 Quick Start, 전체 안내는 Documentation에서 볼 수 있다. 저장소는 GitHub에 공개돼 있다.

저장소 분석과 질의

Eulix는 문자열 검색 도구가 찾는 텍스트와, 언어 서버(LSP)가 이미 알고 있는 기호 사이의 정보를 다루려 한다. 호출자와 피호출자, 의존성, 타입, 하위 시스템, 구현 경로를 색인하고 주변 맥락과 함께 검색한다. 제작자는 Eulix가 코드 이해를 전적으로 LLM에 맡기는 대신 색인과 검색을 중심에 두고, 실제 추론이 필요할 때만 LLM을 더한다고 설명한다.

기능은 정확한 기호 조회, 어휘 검색, 의미 벡터 검색, 하위 시스템 신호, 호출 그래프 확장, MMR 기반 다양성 순위화를 결합한다. 질의를 분류해 저장소의 사실은 결정적 조회로, 코드 탐색 질문은 구조 데이터로, 더 깊은 의미 질문은 검색과 선택적 LLM 추론으로 보낸다. 답변에는 검색한 코드 맥락을 사용한다.

Eulix는 Linux 커널 분석에서 3,730만 줄을 57.2초에 파싱했다고 보고한다. 이 수치는 로컬 Linux 커널 분석 실행 결과이며 파서 처리량이 코드의 완전한 의미 이해를 뜻하지는 않는다. 비교표의 내용도 각 도구와 설정의 모든 경우가 아니라 일반적인 기능을 설명한다고 프로젝트는 단서를 달았다. 원격 LLM 제공자를 설정하면 검색된 코드 맥락이 해당 제공자에게 전송될 수 있다.

Linux 커널 기준 요약 수치는 다음과 같다. 처리량은 12개 스레드에서 파서 전체 과정 기준 약 초당 65만 줄이다. 호출 그래프는 파싱 실패 없이 노드 77만 3,000개와 간선 151만 개를 추출했다. 임베딩은 소비자용 GPU 한 대에서 83만 7,531개 청크를 로컬 처리했다. 파싱, 색인, 검색, 임베딩은 모두 기기에서 실행할 수 있다.

지원 언어는 C, C++, Go, Java, JavaScript, Python, Rust, TypeScript다. JSX와 TSX는 현재 지원하지 않는다. C와 C++는 매크로 확장을 하지 않으므로 파싱 정확도가 100%에 이르지 않을 수 있다. 관계 해석 엔진 PRISM은 대규모 코드 탐색을 위해 근사적으로 관계를 해석하며, 형식적인 전체 프로그램 검증 시스템은 아니다. 동적 디스패치, 리플렉션, 간접 호출, 생성 코드, 언어별 메타프로그래밍, 드문 문법에 대한 파서 지원 공백에서는 관계 해석이 최선 노력 방식으로 이뤄진다.

검색 품질은 질문의 구체성, 저장소 구조와 색인 설정, 임베딩 모델, 맥락 한도, 언어 의미에 영향을 받는다. 깊은 다중 단계 연결의 완전한 검색은 보장되지 않는다. 기호 이름이나 파일 경로를 질문에 넣으면 검색 범위를 좁힐 수 있다. 임베딩 모델 선택은 특히 난해한 식별자와 분야별 어휘의 의미 검색 재현율에 영향을 준다. 모델은 설정할 수 있으며, 프로젝트는 더 강한 모델을 커널 규모에서 평가하고 있다. 순위화 품질이 좋아져도 검색은 증명 시스템이 아니다. 자세한 제약은 Known Issues에 정리돼 있다.

설치와 사용

빠른 시작 안내는 Linux 또는 Windows를 대상으로 한다. Linux에는 bash와 curl이 필요하다. Windows에서는 PowerShell이 필요하며, C++ 워크로드가 포함된 Visual Studio Build Tools를 설치해야 할 수도 있다. macOS 바이너리는 아직 시험되지 않았으며, 문제가 생기면 이슈를 등록해 달라고 안내한다.

Linux 설치 명령은 다음과 같다.

bash <(curl -fsSL https://raw.githubusercontent.com/Nurysso/eulix/main/install.sh)

Windows에서는 다음 명령을 사용한다.

irm https://raw.githubusercontent.com/Nurysso/eulix/main/install.ps1 | iex

저장소 디렉터리에서 설정 파일을 만들고 분석과 색인을 실행한다.

cd your-project

eulix init # creates eulix.toml
eulix analyze # parse + build the index

프로젝트 안내에 따르면 eulix analyze의 파서 처리량은 초당 약 65만 줄이며, 100만 줄 저장소는 수 초가 걸린다. 의미 임베딩은 큰 저장소에서 시간이 오래 걸리는 단계이며, 개방형 질문에 답하고 싶을 때만 필요하다. Linux 커널의 호출 그래프 생성은 57초였고 RDNA2 GPU에서 83만 7,000여 개 청크의 임베딩은 약 27분이 걸렸다.

대화형 질의와 한 번만 실행하는 질의는 다음과 같다.

eulix chat # interactive
eulix query "Who calls foo?" # one-shot

클라우드 계정이나 API 키 없이 사용할 수 있다. 각 질문은 분류를 거쳐 답할 수 있는 가장 간단한 경로로 전달된다. 예를 들어 기호 위치는 정확한 기호 조회, 호출자는 호출 그래프, 프로젝트 지표는 프로젝트 메타데이터로 처리하며 이 질문에는 LLM이 필요하지 않다. 하위 시스템 작동 방식은 검색과 구조적 관계를 이용하며 LLM이 필요한 경우는 드물다. 원인을 묻는 질문은 검색과 추론을 거치며 LLM을 사용한다. 프로젝트는 대부분의 질문에 모델을 호출하지 않고 생성된 저장소 데이터로 답하므로 빠르고 무료이며 결정적이라고 설명한다.

기호, 함수 이름, 파일 경로 같은 명시적 단서는 정확한 조회와 그래프 확장을 돕는다. 개방형 질문은 의미 신호와 하위 시스템 신호에 더 의존한다. 프로젝트는 Django의 Expression.resolve_expression()과 OuterRef, Query의 Set 속성, SQLCompiler.get_from_clause()가 상관 하위 쿼리에서 테이블 별칭을 어떻게 처리하는지 묻는 다중 단계 질문을 예로 든다. OpenStack Nova의 PCI 패스스루 요구 인스턴스 스케줄링과 자원 확보 과정에 참여하는 필터를 묻는 질문도 교차 영역 사례로 제시한다.

주요 CLI 명령은 init(현재 저장소 초기화), analyze(파싱·분석·임베딩 및 저장소 데이터 생성), chat(대화형 인터페이스), query(검색 맥락 생성 또는 직접 질의), mcp(코딩 에이전트용 표준 입출력 MCP 서버), vizEulize(브라우저에서 호출 그래프 탐색기 실행), parser(파서 래퍼 접근), embed(임베딩 파이프라인만 실행), history(이전 질의 확인), version(구성 요소 버전 표시), verifyBins(포함된 바이너리 해시 검증), checksum(저장소 체크섬 갱신)이다.

에이전트·편집기·탐색기

CLI는 공통 엔진을 사용하는 여러 인터페이스 가운데 하나다. 각 구성 요소는 같은 로컬 색인을 읽는다. CLI eulix, 브라우저 호출 그래프 탐색기 vizEulize, 독립 Rust 크레이트 libeulix는 안정 버전으로 표시돼 있다. 다국어 언어 서버 eulix-lsp와 코딩 에이전트용 eulix mcp는 베타다.

MCP 서버는 Claude Code, Windsurf, Cline, Continue, LM Studio 같은 에이전트가 분석된 저장소를 질의하고 순위가 매겨진 소스 맥락을 받도록 한다. 질의 사이에 지식 기반을 유지하고 필요에 따라 저장소를 바꾸며, 에이전트가 이미 알고 있는 known_symbols에 맞춰 검색을 조정한다. 저장소마다 한 번 분석한 뒤 서버를 실행하는 예시는 다음과 같다.

eulix analyze # once per repository
eulix mcp --repo /path/to/repo # stdio MCP server

MCP 설정 예시는 다음과 같다.

{
 "mcpServers": {
 "eulix": {
 "command": "eulix",
 "args": ["mcp"]
 }
 }
}

클라이언트가 셸의 PATH를 상속하지 않으면 command에 절대 경로를 쓰라고 안내한다. 서버가 제공하는 도구는 query, query_with_cot, query_without_cot, set_repo_path다. 자세한 내용은 MCP README에 있다.

베타인 eulix-lsp는 libeulix 기반 다국어 언어 서버다. 문서 개요, 마우스 오버 정보, 정의로 이동, 참조 찾기, 자동 완성, 열린 버퍼의 이름 변경, 의미 토큰, 호출 계층, 접기 범위, 작업 공간 기호, 작업 공간 진단 기능을 제공한다. 빌드한 바이너리를 편집기의 LSP 클라이언트에 지정하면 된다.

cd eulix-lsp
cargo build --release
./target/release/eulix-lsp

전체 기능과 의도적으로 구현하지 않은 항목은 eulix-lsp README에 설명돼 있다.

호출 그래프 탐색기는 다음 명령으로 실행한다.

eulix analyze
eulix vizEulize

vizEulize는 127.0.0.1에서 로컬 서버를 시작하고 브라우저에 검색 가능한 대화형 호출 그래프를 연다. 초점, 방향, 깊이 조절과 필터, 태그, 범주 기능을 제공하며 모든 데이터는 사용자의 기기에 머문다고 설명한다. 자세한 내용은 vizEulize README를 참고하면 된다.

분석 엔진은 독립형 Rust 크레이트로 사용할 수 있다.

cargo add libeulix

crates.io의 libeulix에서 패키지를 확인할 수 있으며, 소스는 libeulix/에 있다.

구성과 데이터 처리

구성 요소는 작업에 맞는 언어로 작성됐다. libeulix/는 Rust와 Tree-sitter를 사용하는 분석 엔진으로, 소스 검색, 기호 추출, 관계 및 호출 그래프 분석, 색인, 지표, 진입점을 처리한다. eulix-parser/는 libeulix의 Rust CLI 프런트엔드이며, 메모리 사용량을 낮추기 위한 디스크 넘김 직렬화 방식으로 지식 기반을 .eulix에 기록한다.

eulix-embed/는 Python 기반 스트리밍 임베딩 파이프라인이다. PyTorch 또는 ONNX, CPU 또는 GPU, INT8 또는 SQ8 양자화, 서비스 모드, 메모리 매핑 벡터 저장소를 지원한다. eulix-cli/는 Go로 작성됐으며 오케스트레이션, 질의 분류와 라우팅, 맥락 구성, LLM 통합, MCP 서버, vizEulize 실행을 맡는다. eulix-lsp/는 libeulix 기반 Rust 언어 서버이며 베타다. vizEulize/는 단일 파일 HTML/JS 호출 그래프 탐색기다.

PRISM은 대규모 코드 탐색을 위해 만든 근사 관계 해석 엔진이다. 형식적인 전체 프로그램 검증을 제공하지 않는다. 설계는 Parser Architecture에서 볼 수 있다. 검색 과정은 명시적 단서와 경로 제한을 먼저 적용한 뒤 정확한 기호 검색, BM25 기반 어휘 검색, IVF 벡터 의미 검색을 결합한다. 결과를 병합·중복 제거하고 하위 시스템 신호를 반영한다. 범위와 테스트 파일의 순위를 낮춘 뒤 MMR 및 정확한 일치 우선 순위화를 적용해 맥락을 선택한다.

저장소의 eulix.toml에서 설정한다. 최소 구성 예시는 다음과 같다.

[project]
 path = "/absolute/path/to/your/repo"

[parser]
 threads = 8
 prismVersion = 2 # 1 = fast/direct, 2 = precise/scope-aware

[embeddings]
 model = "BAAI/bge-base-en-v1.5"
 dimension = 768
 engine = "onnx" # "onnx" or "torch"

[llm]
 local = true # set false to use a cloud provider
 provider = "ollama" # ollama, openai, anthropic, gemini, deepseek, …
 model = "deepseek-r1:14b"

MMR 다양성, 그래프 확장 깊이, 저장소 루트 간 격리, 후보 한도 등은 [retrievalConfig] 아래에서 조정할 수 있다. 주석이 포함된 전체 옵션은 설정 참조에 있다. path는 절대 경로여야 한다. 저장소를 옮기거나 eulix.toml을 다른 프로젝트에 복사하면 경로를 갱신해야 한다.

eulix analyze는 저장소에 .eulix 디렉터리를 생성한다. 여기에는 기호·함수·클래스·메서드를 담은 kb.json, 조회 색인 kb_index.json, 호출 그래프와 역방향 호출 그래프 kb_call_graph.json, 프로젝트 요약과 지표 kb_summary.json이 들어간다. 임베딩을 생성하면 양자화 임베딩 embeddings.bin과 벡터 저장소 vectors.bin도 만들어진다. Linux 커널 기준 두 파일은 각각 약 617MB와 50MB다. 커널 규모 저장소에서는 약 1.2GB의 디스크 공간이 필요하며, 파서의 최대 상주 메모리(RSS)는 약 3.3GiB다.

분석과 검색 전체 과정은 로컬에서 실행할 수 있으며 LLM 단계는 선택 사항이다. Ollama 같은 로컬 제공자를 쓰면 환경 밖으로 데이터가 나가지 않는다. 다만 원격 제공자를 설정하면 질의마다 검색된 코드 맥락이 해당 제공자에게 전송된다. 독점 저장소를 다룰 때는 이 점을 고려해야 한다.

성능 측정과 적용 범위

프로젝트가 제시한 측정은 로컬 엔지니어링 실행에서 나온 결과다. 하드웨어, 저장소 상태, 파서 설정, 임베딩 모델, 질문 형태에 따라 달라질 수 있다. Linux 커널 파서 측정은 파일 6만 4,460개, 코드 3,730만 줄, 실패 0건이며, 12개 스레드와 PRISM v2에서 57.2초가 걸렸다.

단계별 측정에서 파싱에는 52.23초와 RSS 1,963.2MB가 들었다. PRISM v2 호출 그래프 생성은 1.34초, 요약과 지표 생성은 0.34초와 3MB였다. 분석 단계의 메모리는 803MB였고 기록 단계의 최고 메모리는 약 3.3GiB였다. 직렬화는 파서의 내부 표현 전체 대신 축약된 저장소 뷰를 사용해 디스크로 넘기는 구조다. 프로젝트는 이 방식으로 최고 RSS를 약 8GB에서 3.3GiB로, 디스크 출력량을 약 2.2GB에서 1.2GB로 줄였다고 보고한다.

파싱 결과는 정상 32,338건, 부분 파싱 32,122건, 실패 0건이다. 부분 파싱은 대부분 C/C++ 코드이며, 전처리기 단계가 없는 상황에서 예상되는 결과라고 설명한다.

임베딩 측정은 AMD Radeon RX 6700 XT(ROCm/HIP), BAAI/bge-base-en-v1.5, 768차원, SQ8/INT8 설정에서 이뤄졌다.

이 실행에서 파싱은 약 1분이었으며 임베딩은 처리량이 제한되는 단계로 가속기 성능에 따라 달라진다. 프로젝트는 중급 소비자용 GPU 한 대의 수치를 보편적인 기준으로 취급하지 않고 하드웨어별 결과를 따로 측정한다고 덧붙였다.

Linux 커널 외에 Go 컴파일러, FFmpeg, Gecko / Firefox, Django, OpenStack Nova에서 검증했다고 밝혔다. 지원 언어별 안내는 C와 C++가 매크로 확장 한계로 부분 제약을 받고, Go는 kubernetes와 gin-gonic, Python은 Django와 Openstacks, Rust는 RipGrep과 Zed에서 검증됐다고 적는다. TypeScript는 Deno에서 검증했으며 TSX 파일을 파싱하지 못한다. JavaScript는 Express.js와 Three.js에서 검증했으며 JSX 파일은 파싱하지 못한다. Java는 Tomcat과 OpenJDK에서 검증됐다.

프로젝트 상태와 자료

프로젝트가 완료한 항목에는 대화형 호출 그래프 시각화 vizEulize, 에이전트에 검색 기능을 제공하는 eulix mcp, 재사용 가능한 독립 분석 크레이트 libeulix, 베타 다국어 언어 서버 eulix-lsp가 포함된다. JavaScript와 Java도 Tomcat, OpenJDK, Express.js, Three.js에서 검증했다고 안내한다. 다음 작업으로 저장소 규모 벤치마크 추가, 아키텍처를 반영한 문서 생성, 어려운 식별자와 깊은 의미 질의를 위한 더 강한 임베딩 모델, 사용자 연구와 어려운 질의 집합 확대를 제시한다.

문서는 핵심 안내인 About Eulix, Installation, Model Selection을 비롯해 시스템 개요, 질의 파이프라인, 파서 내부, 맥락 구성기, 캐시 구조, 임베딩 파이프라인의 아키텍처 문서를 제공한다. 분류기, 질의 패키지, 파서 구조 자료도 있다. CLI, MCP 서버, 파서, LSP, vizEulize별 안내와 알려진 문제도 공개돼 있다.

문서는 최신 구조를 반영하도록 갱신 중이며, 일부 내부 설계 문서는 이전 버전의 Eulix를 설명할 수 있다. 진행 중인 문서 개편은 이슈 #64에서 확인할 수 있고, 자동 생성 문서는 DeepWiki에서 볼 수 있다.

Eulix는 활발히 개발 중이다. 프로젝트는 이슈, 벤치마크, 문서 개선, 언어 지원, 파서 작업, 검색 실험, 실제 환경의 어려운 테스트 사례를 기여로 받는다. 복잡한 저장소에서 답하기 어려운 질의가 있으면 이슈를 등록해 검색 로드맵에 반영할 수 있다. 큰 변경은 구현 전에 접근 방식을 논의할 수 있도록 먼저 이슈를 열어 달라고 안내한다.

저장소 구성은 eulix-cli/(Go CLI·라우팅·검색·LLM 계층 및 MCP), eulix-embed/(Python 임베딩 파이프라인), eulix-parser/(Rust 파서 CLI), libeulix/(Rust PRISM 분석 엔진), eulix-lsp/(Rust 다국어 언어 서버, 베타), vizEulize/(HTML/JS 호출 그래프 탐색기)로 나뉜다. 모든 구성 요소는 Apache 2.0 라이선스다.

로컬에서 프로젝트를 빌드할 때는 저장소를 복제하고 빌드 스크립트를 실행한다.

git clone https://github.com/Nurysso/eulix.git
cd eulix

bash build.sh # build all components

eulix version
eulix verifyBins

Rust 구성 요소(libeulix, eulix-parser, eulix-lsp)에서는 각 디렉터리에서 포맷, 린트, 테스트를 실행하도록 안내한다. Go CLI에서는 다음을 실행한다.

# Rust: libeulix, eulix-parser, eulix-lsp (run in each directory)
cargo fmt --check
cargo clippy
cargo test

# CLI (Go)
cd eulix-cli
gofmt -l .
go vet ./...
go test ./...

기여 절차는 변경 사항이나 어려운 질의를 설명하는 이슈를 열고, 저장소를 포크해 기능 브랜치를 만든 뒤, 변경한 구성 요소의 포맷·린트·테스트를 실행하고, 이슈를 연결한 풀 리퀘스트를 여는 순서다.

Eulix는 Apache License 2.0으로 배포된다. 이 라이선스는 CLI와 MCP 서버, 파서, libeulix, 임베딩 파이프라인, 언어 서버, vizEulize에 적용된다. 프로젝트는 libeulix의 파싱 기반인 Tree-sitter, 임베딩 백엔드인 PyTorch와 ONNX Runtime, 기본 임베딩 모델 BAAI/bge-base-en-v1.5, 로컬 LLM 제공자 Ollama, 자동 생성 문서 DeepWiki, eulix-lsp의 LSP 프로토콜 구현 tower-lsp, eulix mcp에서 쓰는 Go용 모델 컨텍스트 프로토콜 SDK go-sdk에 기반한다고 밝혔다. Linux 커널, Go 컴파일러, FFmpeg, Gecko / Firefox, Django 같은 대형 오픈소스 저장소를 대상으로 개발과 부하 시험을 진행하고 있다고 설명한다.