Show HN: Mole – 터미널용 심층 리서치 에이전트

질문을 던지면, mole은 이를 분해하고, 검색하며, 출처를 읽고, 주장(claims)을 추출하고, 각 주장을 해당 텍스트와 비교 검증하며, 그들 사이의 모순점(contradictions)을 찾고, 인용구와 함께 답변을 작성합니다. 모든 모델 호출(model call)은 발생하기 전에 예산에 할당되고 나중에 정산되므로, 설정한 상한선이 곧 도달하는 상한선입니다.

이는 사용자의 기기에서 단일 정적 바이너리(single static binary)로 실행되며, 자체 API 키를 사용하고, MCP를 통해 통신하여 코딩 에이전트가 이를 구동할 수 있습니다. 즉, mole에게 질문을 던지고 답변을 취합하는 방식이거나, **툴킷 모드(toolkit mode)**에서 자신의 모델로 추론을 수행하면서 mole은 모델 호출이 아닌 부분을 공급하는 방식입니다.

왜 mole인가 (Why mole)

mole이 웹 검색을 하는 채팅 인터페이스와 다른 세 가지가 있습니다.

예산은 추정되는 것이 아니라 강제됩니다(The budget is enforced, not estimated). 모든 호출은 데이터베이스 스키마 자체에 비음수 제약 조건(non-negative constraints)을 가진 원장에 기록되어 발생 전에 예약되고 나중에 정산됩니다. --usd 0.50은 실행이 50센트에서 중단됨을 의미합니다. 테스트 코퍼스 전반의 측정 초과 사용량(Measured overshoot)은 0%입니다.

모든 주장은 출처를 지니며, 이는 검증됩니다(Every claim carries a quote, checked against the source). 추출 시점에 해당 페이지에서 문구 그대로(verbatim) 나타나지 않는 인용구를 가진 주장은 폐기되며, 답변에 도달하기 전에 걸러집니다. 살아남은 주장들은 나중에 그 출처와 다시 읽어볼 수 있으며, 지원되지 않는 것으로 판명된 경우 조용히 무시되는 대신 보고서에 그렇게 표시됩니다.

로컬 데이터는 로컬에 머무릅니다. mole을 CSV 또는 폴더를 가리키게 하면, 내용물이 기기를 벗어나지 않은 채 분석합니다. 모델은 가설 템플릿과 열 이름을 선택하고, mole이 SQL을 렌더링하고 실행하며, 집계된 결과(개수, 평균, 테스트 결과, 최소 5개의 레코드를 포함하는 버킷)만 되돌아옵니다. mole crossings는 정확히 무엇이 나갔는지 보여줍니다.

설치 (Install)

스크립트 (Script) — Linux 및 macOS, amd64 및 arm64:

curl -fsSL https://raw.githubusercontent.com/lajosdeme/mole/main/install.sh | sh

플랫폼에 맞는 릴리스 아카이브를 다운로드하고, 릴리스와 함께 게시된 체크섬과 SHA-256을 검증한 후, mole과 mole-mcp를 ~/.local/bin (또는 쓰기 가능한 경우 /usr/local/bin)에 설치합니다. 대상 디렉토리가 필요로 할 때만 sudo를 사용하며, --dry-run은 어떤 작업을 수행할지 보여줍니다. 스크립트를 셸에 파이프하는 것이 불안하다면 — 그럴 수 있습니다 — 먼저 읽거나 아래 경로 중 하나를 사용하세요.

Homebrew — macOS 및 Linux:

brew install lajosdeme/mole/mole

완전한 한정 범위(Fully qualified)여야 하며, 그래야 합니다: homebrew/core에는 관련 없는 mole (macOS 정리 도구)이 있어, brew install mole은 항상 그 것을 의미할 것입니다. 둘 다 mole이라는 바이너리를 설치하므로, 한 번에 하나만 연결될 수 있습니다.

Arch Linux — AUR에서:

yay -S mole-research-bin      # 사전 빌드 릴리스 바이너리
yay -S mole-research          # 소스에서 빌드

mole이 아닙니다: 그 이름과 AUR의 mole-bin은 2020년부터 이를 보유해 온 SSH 터널링 도구에 속합니다. 이 패키지는 /usr/bin/mole을 설치하고 충돌을 선언하므로, pacman이 무언가를 덮어쓰기보다는 알려줄 것입니다.

Debian 및 Ubuntu — 릴리스 페이지의 .deb:

curl -fsSLO https://github.com/lajosdeme/mole/releases/latest/download/mole_amd64.deb
sudo dpkg -i mole_amd64.deb

동일한 플랫폼에 대해 .rpm이 게시됩니다.

소스에서 (From source) — Go 1.25+ 필요:

동일한 플랫폼에 대해 .rpm이 게시됩니다.

소스에서 (From source) — Go 1.25+ 필요:

go install github.com/lajosdeme/mole/cmd/mole@latest
go install github.com/lajosdeme/mole/cmd/mole-mcp@latest

또는 클론하여 make install을 실행하면, 버전이 태그를 보고하도록 설정되어 mole version에서 'dev' 대신 태그가 표시됩니다.

모든 경로는 동일한 것을 설치합니다: 런타임 의존성이 없는 두 개의 정적 바이너리이며, CGO_ENABLED=0으로 빌드되었습니다. 데이터베이스는 SQLite이며, 처음 사용 시 XDG 데이터 디렉터리에 생성됩니다.

설정 (Configure)

검색 제공자(search provider)와 모델 제공자(model provider)가 필요합니다. 키는 ~/.config/mole/config.json에 위치하며, 권한 모드는 0600입니다. 프로세스 목록에 노출되는 환경 변수나 .mcp.json에는 절대 넣지 마십시오.

mole config set search.provider tavily          # 또는: brave
mole config set search.tavily-key tvly-... 

OpenAI와 호환되는 모든 엔드포인트가 작동합니다 — DeepSeek, Ollama, llama.cpp, vLLM, 프록시:

mole config set llm.provider openai-compatible
mole config set llm.base-url https://api.deepseek.com/v1
mole config set llm.model deepseek-chat

localhost에서 제공되는 모델은 비용이 0으로 책정되지만 토큰 수에는 여전히 계산되므로, --tokens는 전혀 비용이 들지 않는 자체 호스팅 실행에 제한을 겁니다.

사용법 (Usage)

질문 리서치하기 (Research a question)

mole research "비트코인 네트워크가 사용하는 전력량은 얼마인가요?" --usd 0.50
mole research "..." --tokens 200000            # 달러 대신 토큰 예산 사용
mole research "..." --max-sources 8 --max-depth 3
... 

예산이 필요하며, 두 단위는 상호 배타적입니다. 검색 호출에 비용을 책정할 수 있는 것은 달러 모드뿐이며, mole가 비율을 알지 못하는 모델의 경우 토큰 모드로 제한해야 합니다.

후속 질문하기 (Ask a follow-up)

mole ask <세션-id> "캠브리지 추정치는 뭐라고 했나요?"

답변은 해당 세션이 이미 수집한 주장(claims)들로부터 나옵니다. 새로운 검색이나 답변을 구성하기 위한 단 한 번의 호출 외에는 추가적인 지출이 없습니다.

산문 대신 데이터셋 구축하기 (Build a dataset instead of prose)

mole research "largest UK supermarket chains and their revenue" \
  --mode dataset \
  --schema 'company:text!,revenue:number=annual revenue in GBP,employees:number'
...

!는 행을 식별하는 필드를 나타냅니다. 여러 소스에서 가져온 행들은 퍼지 키(fuzzy key)를 통해 병합되므로, Aldi와 Aldi UK는 두 개의 소스를 가진 하나의 행이 됩니다. CSV는 셀당 하나의 값을 가지며 이를 명시합니다. 즉, 소스 개수와 소스들이 의견을 달리하는 필드를 나타내는 contested 열을 포함합니다. JSON은 각 소스별로 의견이 다른 모든 값을 담고 있습니다.

로컬 데이터 분석 (Analyse local data)

mole connect add sales ./exports/sales.csv       # 파일 하나일 경우
mole connect add exports ./exports               # 또는 전체 폴더의 경우
mole research "지역별 지출은 어떻게 다른가요?" \
...

CSV, TSV, JSON, JSONL 형식이 지원되며 Parquet은 지원하지 않습니다. 모델은 절대 행을 보지 않으며 SQL을 작성하지도 않습니다. 대신 템플릿과 열 이름을 선택하고 mole이 해당 구문을 렌더링합니다.

MCP 클라이언트 서비스 (Serve MCP clients)

mole serve

유닉스 소켓(unix socket)의 0600 모드로 비공개 디렉터리에서 리스닝하며, 다른 사용자로부터의 연결은 거부합니다. 클라이언트를 shim에 지정하세요:

{
  "mcpServers": {
    "mole": { "command": "mole-mcp" }
...
}

이 파일에는 자격 증명(credentials)이 없으며, shim이 데몬(daemon)으로 포워딩하고 데몬이 이를 보유합니다.

이미 지불한 구독 사용하기 (toolkit mode)

mole serve --toolkit

위의 구성에서는 mole이 모델을 소유합니다. 즉, API 키를 사용하여 계획하고, 채굴하며, 작성하는 것이고, 이를 구동하는 코딩 에이전트는 버튼을 누르는 행위에 가깝습니다. 툴킷 모드(Toolkit mode)는 이 상황을 반전시킵니다. 에이전트의 모델이 추론을 수행하고; mole은 결정론적인 절반(deterministic half)을 기여합니다. — 이것이 가치가 있는 절반이자, 다른 쪽 끝에 어떤 모델이 있든 상관하지 않는 절반입니다.

만약 Claude Code나 Qwen Code 같은 서비스에서 구독 중이라면, 사용자의 모델 토큰은 이미 지불된 상태입니다. 이 모드가 바로 그런 경우를 위한 것입니다.

mole.<tool>이라는 이름의 14개 도구와 research.* 도구들이 있으며 — 이 플래그는 하나를 대체하기보다는 표면적인 추가 기능을 제공합니다:

실행 검사 (Inspect a run)

mole sessions                # 최근 세션 및 비용 확인
mole trace <세션-id>      # 호출별 비용 및 시간 분석
mole stats --fetch           # 세션 전반에 걸친 가져오기 실패 원인

작동 방식 (How it works)

question
   ↓  planner            하위 질문으로 분해하고, 증거가 도착함에 따라 재계획(replan) 수행
   ↓  executor           작업자당 한 번에 하나의 리드(lead)를 처리하며, 예약 및 확정됨
...

세 가지 액터 유형이 동일한 그래프에 데이터를 공급합니다. web은 검색을 수행하고 페이지 내용을 읽습니다.
academic은 Crossref, OpenAlex, arXiv, PubMed에서 쿼리하며 DOI로 중복 제거를 하고 오픈 액세스 전문(full text)을 우선시합니다. local_compute는 사용자가 등록한 데이터에 대해 결정론적 SQL을 실행하며, 어떤 행도 모델에 도달하지 않도록 합니다.

툴킷 모드(Toolkit mode)는 화살표 방향이 반대인 동일한 메커니즘을 실행합니다: 에이전트가 무엇을 검색하고, 무엇을 읽고, 어떤 주장이 관련되는지 결정하며, mole은 인용 확인(quote checking), 쌍 검색(pair retrieval), 병합(merging), SQL 렌더링을 수행합니다. 두 모드는 각각의 복사본 하나를 공유합니다 — 데이터셋 행에 대한 동일한 AcceptRow, 동일한 집계 게이트(aggregation gate), 동일한 어휘 검색기(lexical retriever)가 사용되어, 툴킷 그래프와 자율 그래프 모두 같은 방식으로 구축됩니다.

실제 수치 (Honest numbers)

mole은 자체 실행에 대한 평가를 수행합니다. mole eval <세션-id>는 점수표(scorecard)를 출력하며, 계산할 수 없는 모든 지표는 조용히 0을 읽는 대신 그 사실을 명시합니다.

기여하기 (Contributing)

버그 보고 및 이슈 제기는 환영합니다. 코드 기여는 CLA(Contributor License Agreement)를 거칩니다 — CONTRIBUTING.md에서 이것이 무엇을 위한 것이고 무엇을 할 수 없는지 설명합니다.

유지 관리자: 릴리스 실행 가이드북은 RELEASING.md입니다.

이 프로젝트가 요구하는 가장 까다로운 관행은 대부분의 사람들이 하지 않는 것입니다: 자신이 수정한 부분을 반증(falsify)해 보는 것.
변경 사항을 적용한 후, 해당 메커니즘을 되돌리고 테스트가 실패하는지 확인하세요. 수정 사항을 제거해도 통과하는 테스트는 아무것도 증명하지 못하며, 이 프로젝트의 자체 테스트 중 여러 개가 정확히 그렇게 하고 있는 것이 적발된 바 있습니다.

gofmt -l .      # 아무것도 출력해서는 안 됨
go build ./... 
go test ./...   # 깨끗해야 하며, 새로운 건너뛰기(skip)가 없어야 함

라이선스 (Licence)

Apache-2.0. LICENSE와 NOTICE를 참조하세요.