Semble – AI 에이전트용 코드 검색 도구, grep 대비 토큰 98% 절감 | AI Paper Digest

TL;DR Highlight

AI 에이전트가 코드베이스를 탐색할 때 grep+파일 읽기 대신 자연어로 관련 코드 스니펫만 뽑아주는 검색 라이브러리로, 토큰 사용량을 약 98% 줄여준다.

Who Should Read

Claude Code, Cursor, Codex 같은 AI 코딩 에이전트를 활용 중인데 토큰 비용과 응답 지연을 줄이고 싶은 개발자. MCP 서버나 bash 도구로 바로 통합할 수 있어서 에이전트 워크플로우를 개선하려는 사람에게 적합하다.

Core Mechanics

Semble은 AI 에이전트가 코드를 탐색할 때 기존의 'grep으로 파일 검색 → 파일 전체 읽기' 패턴 대신, 자연어 쿼리(예: 'How is authentication handled?')로 관련 코드 스니펫만 즉시 반환하는 방식을 사용한다.
토큰 사용량이 grep+파일 읽기 방식 대비 약 98% 줄어든다. grep은 파일 전체를 에이전트 컨텍스트에 넣어야 하는 반면, Semble은 딱 필요한 코드 블록만 돌려준다.
전체 코드베이스 인덱싱과 검색을 합쳐서 1초 이내에 완료된다. 코드 특화 트랜스포머 모델 대비 인덱싱 속도는 약 200배 빠르고, 쿼리 속도는 약 10배 빠르다.
검색 품질은 코드 특화 트랜스포머 모델의 99% 수준을 유지한다. 속도를 위해 품질을 크게 희생하지 않는다는 점이 핵심이다.
GPU, API 키, 외부 서비스가 전혀 필요 없고 CPU만으로 동작한다. 로컬 환경에서 완전히 독립적으로 실행 가능하다.
MCP(Model Context Protocol) 서버로 실행하거나, AGENTS.md/CLAUDE.md에 bash 도구로 등록하는 두 가지 방식으로 에이전트에 통합할 수 있다. Claude Code, Cursor, Codex, OpenCode 등 주요 에이전트 하네스를 모두 지원한다.
Claude Code에 MCP로 추가하는 명령어는 `claude mcp add semble -s user -- uvx --from 'semble[mcp]' semble` 한 줄이면 된다. pip이나 uv로도 설치 가능하다.
GitHub 기준 Star 1k, Fork 69개를 기록하며 커뮤니티 관심을 받고 있다. MIT 라이선스로 오픈소스다.

Evidence

'grep은 토큰이 0개인데 98% 줄인다는 게 무슨 의미냐'는 의견이 나왔다. 이는 grep 자체가 아니라 grep으로 찾은 파일을 에이전트 컨텍스트에 통째로 올리는 과정에서 토큰이 발생한다는 점을 간과한 지적으로, 마케팅 문구에 대한 비판이다.
RL(강화학습)로 훈련된 모델들이 grep 패턴에 너무 익숙해져 있어서, 다른 도구의 결과를 믿지 못하고 계속 재시도하거나 파일을 다시 읽는 현상이 있다는 실제 경험담이 공유됐다. 이 경우 토큰 절감 효과가 사라진다는 현실적인 문제 지적이다.
에이전트가 bash 도구보다 커스텀 도구를 선호하도록 유도하는 것 자체가 어렵다는 경험담도 있었다. 같은 분야 도구를 만든 개발자가 '에이전트가 bash 도구 대신 이걸 쓰게 만드는 게 가장 큰 도전이었다'고 공유했다.
LSP(Language Server Protocol, 코드 에디터에서 자동완성/정의 이동 등을 지원하는 표준 프로토콜) 대비 장점이 무엇이냐는 질문이 있었다. 실제로 RTK나 LSP 구현체를 탐색해봤는데 결과가 다른 형태로 오면 모델이 신뢰하지 않는다는 경험도 함께 공유됐다.
벤치마크가 원샷(one-shot) 검색 정확도를 측정하는지, 아니면 실제 코딩 에이전트의 태스크 완료율을 측정하는지 묻는 질문이 나왔다. 검색 정확도와 에이전트 실제 성능은 다를 수 있다는 점을 지적한 것이다.

How to Apply

Claude Code를 쓰는데 대형 코드베이스 탐색 시 토큰 비용이 크다면, `claude mcp add semble -s user -- uvx --from 'semble[mcp]' semble` 명령어로 MCP 서버를 등록하면 에이전트가 파일 전체를 읽지 않고 관련 스니펫만 가져오게 된다.
Cursor나 Codex CLI처럼 AGENTS.md를 지원하는 에이전트 환경에서는 `pip install semble` 후 AGENTS.md에 bash 도구 스니펫을 추가하면 된다. MCP와 bash 통합을 동시에 사용하는 것도 지원한다.
로컬 코드베이스 검색 도구를 직접 만들고 있다면, GPU 없이 CPU만으로 1초 이내에 인덱싱이 가능한 Semble의 Python API를 백엔드로 활용하면 별도 외부 서비스 없이 시맨틱 코드 검색 기능을 붙일 수 있다.
에이전트가 '인증은 어떻게 처리되나요?'처럼 자연어로 코드를 묻는 시나리오가 많다면, Semble 도입 전후 토큰 사용량을 비교해보는 것이 좋다. 단, 모델이 커스텀 도구 결과를 신뢰하지 않고 재시도하는 현상이 있는지도 함께 모니터링해야 효과를 정확히 판단할 수 있다.

Code Example

snippet

# Claude Code에 MCP 서버로 추가
claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

# pip으로 설치
pip install semble

# uv로 설치
uv tool install semble

# Python API 사용 예시 (README 기반)
from semble import Semble

semble = Semble()
semble.index("/path/to/your/repo")  # 코드베이스 인덱싱 (1초 이내)
results = semble.search("How is authentication handled?")  # 자연어 검색
for snippet in results:
    print(snippet)

Terminology

MCPModel Context Protocol의 약자. AI 에이전트가 외부 도구(파일 시스템, 검색 등)를 표준화된 방식으로 호출할 수 있게 해주는 프로토콜. USB 포트처럼 도구를 꽂으면 에이전트가 바로 쓸 수 있다.

AGENTS.mdAI 코딩 에이전트(Codex 등)에게 '이 프로젝트에서 사용할 수 있는 도구와 규칙'을 설명해주는 설정 파일. 에이전트가 작업 시작 전에 읽고 참고한다.

LSPLanguage Server Protocol의 약자. VS Code 등 에디터에서 코드 자동완성, 정의로 이동, 리팩토링 등을 지원하기 위한 표준 통신 프로토콜. 에디터와 언어 분석 서버 사이의 공통 언어다.

시맨틱 코드 검색키워드 일치가 아니라 의미(semantic)를 이해해서 코드를 찾는 방식. 예를 들어 'login 처리 로직'을 검색하면 변수명이 login이 아니어도 인증 관련 코드를 찾아준다.

트랜스포머BERT, GPT 등 현대 AI 언어 모델의 기반이 되는 딥러닝 아키텍처. 코드 특화 트랜스포머는 코드 이해에 특화 훈련된 모델로, 품질은 높지만 무겁고 느리다.

uvPython 패키지 관리자. pip보다 훨씬 빠르고, uvx 명령어로 패키지를 설치 없이 바로 실행할 수 있어서 최근 Python 생태계에서 많이 쓰인다.

Semble – AI 에이전트용 코드 검색 도구, grep 대비 토큰 98% 절감