probelabs/probe

우리는 코드를 쓰는 시간보다 읽는 시간이 10배 더 많습니다. Probe는 엔터프라이즈 규모의 코드베이스(codebases)에서 작동하도록 설계된, 내장 에이전트(agent)를 갖춘 코드 및 마크다운 컨텍스트 엔진(context engine)입니다.

오늘날의 AI 코딩 도구들은 원시적인 방식을 사용합니다. 몇몇 파일을 검색(grep)하고, 무작위 줄을 읽으며, 운이 좋기를 바라는 식입니다. 이는 연습용 프로젝트에서는 작동하지만, 실제 코드베이스에서는 무너집니다.

Probe는 읽기와 추론(reasoning)을 위해 구축된 컨텍스트 엔진입니다. Probe는 코드를 단순한 텍스트가 아닌 코드로 취급합니다. AST 파싱(AST parsing)을 통해 구조를 이해하며, 시맨틱 검색(Semantic search)을 통해 중요한 것을 찾아냅니다. 단 한 번의 호출로 완전하고 의미 있는 컨텍스트를 얻을 수 있습니다.

**Probe 에이전트(The Probe Agent)**는 코드 이해를 위해 특수 제작되었습니다. 이 에이전트는 Probe 엔진을 전문적으로 활용하여 전체 코드베이스를 검색, 추출 및 추론하는 방법을 알고 있습니다. 명세 기반 개발(spec-driven development), 코드 리뷰, 온보딩(onboarding), 그리고 작성보다 이해가 선행되어야 하는 모든 작업에 완벽합니다.

단 한 번의 Probe 호출이 다른 도구들이 10회 이상의 에이전트 루프(agentic loops)를 거쳐야 하는 작업을 수행합니다 — 더 깊고, 더 깔끔하며, 노이즈가 훨씬 적습니다.

왜 Probe인가?
빠른 시작 (Quick Start)
기능 (Features)
사용 모드 (Usage Modes)
LLM 스크립트 (LLM Script)
설치 (Installation)
지원 언어 (Supported Languages)
문서 (Documentation)
환경 변수 (Environment Variables)
기여하기 (Contributing)
라이선스 (License)

대부분의 코드 검색 도구는 두 가지 진영으로 나뉩니다: 텍스트 기반(text-based, grep, ripgrep) 또는 임베딩 기반(embedding-based, 인덱싱과 임베딩 모델이 필요한 벡터 검색). Probe는 제3의 길을 택합니다: **설정이 필요 없는 AST 인식 구조적 검색(AST-aware structural search)**입니다.

	grep/ripgrep	임베딩 도구 (Embedding tools) (grepai, Octocode)	Probe
설정 시간 (Setup time)	없음 (None)	몇 분 (인덱싱 + 임베딩 서비스)	없음 (None)
코드 이해도 (Code understanding)	텍스트 전용 (Text only)	텍스트 청크 (함수 중간에서 분할 가능)	AST 인식 (AST-aware) (완전한 함수/클래스 반환)
검색 방식 (Search method)	정규표현식 (Regex)	벡터 유사도 (Vector similarity)	Elasticsearch 스타일의 불리언 쿼리 (boolean queries) + BM25
결과 품질 (Result quality)	라인 파편 (Line fragments)	~512자 청크 (~512-char chunks)	완전한 의미론적 코드 블록 (Complete semantic code blocks)
랭킹 (Ranking)	없음 (라인 순서)	코사인 유사도 (Cosine similarity)	BM25/TF-IDF/SIMD 가속을 활용한 하이브리드 (Hybrid)
외부 의존성 (External dependencies)	없음 (None)	임베딩 API (Embedding API) (Ollama/OpenAI)	없음 (None)
토큰 인식 (Token awareness)	아니요 (No)	부분적 (Partial)	예 (Yes) (`--max-tokens`, 세션 중복 제거 (session dedup))
오프라인 작동 (Works offline)	예 (Yes)	로컬 모델 사용 시에만 가능	항상 (Always)
AI 에이전트 통합 (AI agent integration)	없음 (None)	MCP 서버 (MCP server)	전체 에이전트 루프 (Full agent loop) + MCP + Vercel AI SDK

임베딩 기반 도구들은 어휘 불일치(vocabulary mismatch) 문제를 해결합니다. 즉

에이전트 레이어(agent layer) 없이 검색/쿼리/추출 도구에 직접 접근하는 것을 선호한다면:

{
"mcpServers": {
"probe": {
...

AI 에디터 없이 터미널에서 Probe를 직접 사용하세요:

# Elasticsearch 구문을 사용한 시맨틱 검색 (Semantic search)
npx -y @probelabs/probe search "authentication AND login" ./src
# 42번 라인의 코드 블록 추출
...

터미널에서 어떤 코드베이스에 대해서도 직접 질문을 던지세요:

# 원샷 질문 (One-shot question, 모든 LLM 제공업체와 호환 가능)
npx -y @probelabs/probe@latest agent "How is authentication implemented?"
# 코드 편집 기능 포함
...

코드 인식 (Code-Aware): Tree-sitter AST 파싱을 통해 코드의 실제 구조를 이해합니다.
시맨틱 검색 (Semantic Search): Elasticsearch 스타일의 쿼리 (AND, OR, NOT, 구절, 필터) 지원
완전한 컨텍스트 (Complete Context): 함수 중간에서 끊기는 텍스트 청크(text chunks)가 아닌, 함수, 클래스 또는 구조체 전체를 반환합니다.
제로 인덱싱 (Zero Indexing): 어떤 코드베이스에서도 즉각적인 결과 제공. 임베딩 모델(embedding models), 벡터 데이터베이스(vector databases), 설정 과정이 필요 없습니다.
결정론적 (Deterministic): 동일한 쿼리는 항상 동일한 결과를 반환합니다. 모델의 변동성이나 오래된 인덱스 문제가 없습니다.
완전 로컬 (Fully Local): 코드가 기기를 절대 떠나지 않습니다. 검색을 위한 API 호출이 없습니다.
매우 빠른 속도 (Blazing Fast): SIMD 가속 패턴 매칭 + ripgrep 스캐닝 + rayon 병렬 처리(parallelism)
스마트 랭킹 (Smart Ranking): BM25, TF-IDF 및 선택적 BERT 재순위화(reranking)를 포함한 하이브리드 알고리즘
토큰 인식 (Token-Aware): --max-tokens 예산 설정, 컨텍스트 반복을 방지하기 위한 세션 기반 중복 제거(dedup)
내장된 에이전트 (Built-in Agent): 재시도(retry), 폴백(fallback), 컨텍스트 압축(context compaction) 기능을 갖춘 멀티 제공업체 지원 (Anthropic, OpenAI, Google, Bedrock)
다국어 지원 (Multi-Language): Rust, Python, JavaScript, TypeScript, Go, C/C++, Java, Ruby, PHP, Swift, C#, 그리고 그 이상

AI 에디터와 함께 Probe를 사용하는 권장 방식입니다. Probe 에이전트는 단순한 패턴 매칭이 아니라, 코드를 추론하는 전문 코딩 어시스턴트입니다.

{
"mcpServers": {
"probe": {
...

왜 에이전트를 사용해야 하나요?

코드를 이해하고 추론하도록 특화 설계됨
Claude Code / Codex 인증을 활용 (또는 자체 API 키 사용 가능)
복잡한 질문에 대해 더 스마트한 다단계 추론 (multi-step reasoning) 제공
코드 편집, 작업 위임 (task delegation) 등의 기능 내장

에이전트 옵션 (Agent options):

옵션	설명
`--path <dir>`	검색 디렉토리 (기본값: 현재 디렉토리)
`--provider <name>`	AI 제공자 (AI provider): `anthropic`, `openai`, `google`
`--model <name>`	모델 이름 재정의
`--prompt <type>`	페르소나 (Persona): `code-explorer`, `engineer`, `code-review`, `architect`
`--allow-edit`	코드 수정 허용
`--enable-delegate`	서브 에이전트 (subagents)로의 작업 위임 활성화
`--enable-bash`	bash 명령 실행 활성화
`--max-iterations <n>`	최대 도구 반복 횟수 (기본값: 30)

에이전트 레이어 없이 Probe의 검색 (search), 쿼리 (query), 추출 (extract) 도구에 직접 접근합니다. AI 에디터가 Probe 도구를 직접 호출하도록 하려는 경우 이 방식을 사용하세요.

{
"mcpServers": {
"probe": {
...

사용 가능한 도구 (Available tools):

search

Elasticsearch 스타일의 쿼리를 사용한 시맨틱 코드 검색 (Semantic code search)

query

AST 기반의 구조적 패턴 매칭 (AST-based structural pattern matching)

extract

줄 번호 또는 심볼 이름(symbol name)으로 코드 블록 추출

symbols

파일 내의 모든 심볼(함수, 클래스, 상수)을 줄 번호와 함께 나열

터미널에서 Probe 에이전트를 직접 실행하세요:

# 단발성 질문 (One-shot question)
npx -y @probelabs/probe@latest agent "How does the ranking algorithm work?"
# 검색 경로 지정
...

스크립팅 및 직접적인 코드 분석을 위한 용도입니다.

probe search <PATTERN> [PATH] [OPTIONS]

예시 (Examples):

# 기본 검색
probe search "authentication" ./src
# 불리언 연산자 (Boolean operators, Elasticsearch 구문)
...

주요 옵션 (Key options):

옵션	설명
`--max-tokens <n>`	반환되는 총 토큰 제한
`--max-results <n>`	결과 개수 제한
`--reranker <algo>`	랭킹 (Ranking): `bm25`, `tfidf`, `hybrid`, `hybrid2`
`--allow-tests`	테스트 파일 포함
`--format <fmt>`	출력 형식 (Output): `markdown`, `json`, `xml`

probe extract <FILES> [OPTIONS]

예시 (Examples):

# 42번 라인의 함수 추출 (Extract function at line 42)
probe extract src/main.rs:42
# 심볼 이름으로 추출 (Extract by symbol name)
...

probe symbols <FILES> [OPTIONS]

예시 (Examples):

# 파일 내 심볼 목록 표시 (List symbols in a file)
probe symbols src/main.rs
# 프로그래밍 방식 사용을 위한 JSON 출력 (JSON output for programmatic use)
...

probe query <PATTERN> [PATH] [OPTIONS]

예시 (Examples):

# Rust에서 모든 비동기 함수 찾기 (Find all async functions in Rust)
probe query "async fn $NAME($$$)" --language rust
# React 컴포넌트 찾기 (Find React components)
...

애플리케이션에서 Probe를 프로그래밍 방식으로 사용하세요.

import { ProbeAgent } from '@probelabs/probe/agent';
// 에이전트 생성 (Create agent)
const agent = new ProbeAgent({
...

직접 호출 함수 (Direct functions):

import { search, extract, query, symbols } from '@probelabs/probe';
// 의미론적 검색 (Semantic search)
const results = await search({
...

Vercel AI SDK 통합 (Vercel AI SDK integration):

import { tools } from '@probelabs/probe';
const { searchTool, queryTool, extractTool } = tools;
// Vercel AI SDK와 함께 사용 (Use with Vercel AI SDK)
...

Probe Agent는 결정론적(deterministic)이고 다단계인 코드 분석 작업을 실행하기 위해 execute_plan 도구를 사용할 수 있습니다. LLM Script는 AI가 검색(search), 추출(extraction), 그리고 LLM 추론(reasoning)을 단일 파이프라인으로 결합하여 실행 가능한 계획을 생성하는 샌드박스(sandboxed) JavaScript DSL입니다.

// AI가 생성한 LLM Script 예시 (await은 자동으로 주입되므로 작성하지 마세요)
const files = search("authentication login")
const chunks = chunk(files)
...

주요 기능 (Key features):

에이전트 통합 (Agent integration) - Probe Agent는 스크립트 실행을 위해 execute_plan 도구를 호출합니다.
자동 await (Auto-await) - 비동기 호출은 자동으로 대기됩니다 (await을 작성할 필요가 없습니다).
모든 도구 사용 가능 (All tools available) - search(), query(), extract(), LLM(), map(), chunk() 및 모든 MCP 도구 사용 가능
샌드박스 실행 (Sandboxed execution) - 타임아웃 보호 기능이 있는 안전하고 격리된 JavaScript 환경

구문 및 예시는 전체 LLM Script 문서를 참조하세요.

npm install -g @probelabs/probe

curl -fsSL https://raw.githubusercontent.com/probelabs/probe/main/install.sh | bash

iwr -useb https://raw.githubusercontent.com/probelabs/probe/main/install.ps1 | iex

git clone https://github.com/probelabs/probe.git
cd probe
cargo build --release
...

언어 (Language)	확장자 (Extensions)
Rust	`.rs`
...
전체 문서는 probelabs.com/probe에서 확인하거나 `docs/` 디렉토리에서 로컬로 찾아볼 수 있습니다.

빠른 시작 (Quick Start) - 5분 안에 실행하기
설치 (Installation) - NPM, curl, Docker 및 소스 빌드
기능 개요 (Features Overview) - 핵심 기능
검색 명령어 (Search Command) - Elasticsearch 스타일의 시맨틱 검색 (semantic search)
추출 명령어 (Extract Command) - 전체 AST 컨텍스트를 포함한 코드 블록 추출
심볼 명령어 (Symbols Command) - 파일 내 모든 심볼을 줄 번호와 함께 나열
쿼리 명령어 (Query Command) - AST 기반의 구조적 패턴 매칭
CLI 레퍼런스 (CLI Reference) - 전체 명령줄 레퍼런스
LSP 기능 (LSP Features) - 시맨틱 코드 인텔리전스 (semantic code intelligence)를 위해 --lsp가 추가하는 기능
LSP 빠른 참조 (LSP Quick Reference) - 일상적인 LSP 명령어 치트 시트
인덱싱 개요 (Indexing Overview) - 프로젝트 인덱싱 개념 및 워크플로우
인덱싱 CLI 레퍼런스 (Indexing CLI Reference) - probe lsp index* 명령어 레퍼런스

LSP 기능에는 호출 계층 구조 강화 (extract --lsp), 직접적인 심볼 작업 (probe lsp call definition|references|hover|...), 데몬 진단 (probe lsp logs --analyze), 그리고 워크스페이스 인덱싱 (probe lsp index, probe lsp index-status)이 포함됩니다.

에이전트 개요 (Agent Overview) - Probe Agent란 무엇이며 언제 사용하는가
API 레퍼런스 (API Reference) - ProbeAgent 클래스 문서
Node.js SDK - 전체 Node.js SDK 레퍼런스
MCP 통합 (MCP Integration) - 에디터 통합 가이드
LLM 스크립트 (LLM Script) - 프로그래밍 가능한 오케스트레이션 DSL
쿼리 패턴 (Query Patterns) - 효과적인 검색 전략
Probe 비교 (How Probe Compares) - 임베딩 검색 (embedding search), 지식 그래프 (knowledge graphs), LSP 도구와의 비교
아키텍처 (Architecture) - 시스템 설계 및 내부 구조
환경 변수 (Environment Variables) - 모든 설정 옵션
FAQ - 자주 묻는 질문

# AI 제공자 키 (AI Provider Keys)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
...

기여를 환영합니다! 기여 가이드 (Contributing Guide)를 확인해 주세요.

질문 또는 지원이 필요한 경우:

질문이나 기여를 원하신다면, GitHub에 이슈 (Issue)를 생성하거나 Discord 커뮤니티에 참여하여 토론 및 지원을 받으시기 바랍니다. 즐거운 코딩과 검색이 되길 바랍니다!

probelabs/probe

요약

핵심 포인트

댓글