pluck logo
AI 코딩 에이전트를 위한 MCP-네이티브 코드 검색기
코드 읽기 토큰 84-88 % 절감 · CI 로그 71 % 압축 · 웜 검색 0.07 ms — 모든 수치는 benchmarks/baseline.json의 게이트된 값이에요

Crates.io version License - MIT Rust

[빠른 시작](#빠른-시작) • [왜 pluck을 써야 할까요?](#왜-pluck을-써야-할까요) • [MCP 툴](#mcp-툴) • [CLI](#독립-실행-cli-에이전트-없이) • [성능 및 토큰 절감](#성능-및-토큰-절감-효과)
**pluck**은 AI 에이전트가 코드를 읽고 검색할 때 사용하는 `cat`과 `grep`을 대체하는 로컬 Rust 데몬이에요. MCP(Model Context Protocol)를 통해 심볼(Symbol)을 인식해서 코드를 읽고 검색할 수 있게 해줘요. 스마트 아웃라인은 절감 대상 코드 읽기 토큰을 **84-88 %** 줄이고, CI 로그는 **71 %** 압축하며, 웜 검색은 1밀리초 미만으로 유지돼요. 모든 툴에 `--raw` 폴백을 제공해 에이전트가 pluck을 기본으로 써도 기능 손실이 전혀 없어요. ``` pluck 없이: ls → grep → cat file1 → cat file2 → cat file3 → ... pluck 사용: pluck.plan "auth-token 만료 버그 수정" → 다음 3-5 retrieval 호출 추천 pluck.search "auth flow" → BM25 + 시맨틱으로 랭킹된 청크 pluck.peek validate_token → 시그니처 + 호출 함수만 pluck.symbol validate_token → 해당 함수 본문만 pluck.impact validate_token → 모든 호출자, depth 제한 pluck.deps src/auth/login.ts → 정/역방향 import 그래프 pluck.digest < cargo-build.log → 71% 짧게, 에러는 그대로 ``` ## 빠른 시작 `pluck`은 AI 코딩 에이전트의 기본 검색 도구로 사용되도록 만들어졌어요. ### 1. 에이전트 설정 프롬프트 붙여 넣기 ```text Install and configure pluck for this repo. Install / register: - If pluck is missing, install pluck-mcp and pluck-cli with Cargo or Homebrew. - Register pluckd as an MCP server named `pluck` for this repository. - Prefer project-scoped config when the agent supports it. - Preserve existing MCP servers, rules, hooks, permissions, and comments. To make pluck the first retrieval choice: - Use the strongest official mechanism this agent supports. - Claude Code: use project MCP config or `claude mcp add --transport stdio --scope project pluck -- pluckd --repo `; approve the `pluck` MCP server in settings/permissions when needed; add durable instructions in `CLAUDE.md`; use PreToolUse hooks or permission deny rules only when they can safely redirect repo-local cat/grep/rg/read retrieval to mcp__pluck__* tools. - Codex: use `codex mcp add pluck -- pluckd --repo ` or `~/.codex/config.toml` / trusted project `.codex/config.toml`; add the pluck-first retrieval policy to `AGENTS.md`. - Cursor: use project `.cursor/mcp.json`; add an always-applied Project Rule in `.cursor/rules/` or an `AGENTS.md` instruction for the workspace. Pluck-first retrieval policy: - Use mcp__pluck__read before cat, head, tail, sed -n, or built-in file reads for files inside the indexed repo. - Use mcp__pluck__search for conceptual code lookup. - Use mcp__pluck__grep before grep or rg for exact strings, regexes, TODOs, and all textual matches inside the repo. - Use mcp__pluck__peek, mcp__pluck__symbol, mcp__pluck__expand, mcp__pluck__impact, and mcp__pluck__deps for symbol shape, bodies, call chains, refactor impact, and import relationships. - Use mcp__pluck__digest before pasting long cargo, npm, pytest, or GitHub Actions logs into context. - Fall back to Bash or built-in reads only for binary files, paths outside the repo, byte-exact shell pipelines, unsupported formats, or when pluck is unavailable. Verify: - Restart or reload the agent if MCP changes require it. - Confirm the `pluck` MCP server is connected and mcp__pluck__* tools exist. - Run one repo code-search/read task and confirm the agent calls mcp__pluck__* before Bash, grep/rg, cat, or built-in file reads. - Show the files changed and the verification result. ``` 안전 체크와 폴백 지시를 더 자세히 넣은 버전은 [전체 에이전트 설치 프롬프트](docs/AGENT_INSTALL.md)를 쓰면 돼요. ### 2. 직접 설정하고 싶다면 ```bash # crates.io에서 데몬 + 독립 실행형 CLI 설치 cargo install pluck-mcp pluck-cli # 또는 Homebrew tap을 통해 설치 brew tap hunhee98/pluck && brew install pluck ``` **Claude Code** ```bash pluck init --target claude --mode aggressive # MCP + 권한 + Bash 검색 차단 ``` *(수동으로 추가하려면 `/plugin marketplace add hunhee98/pluck`을 입력해도 돼요)* **Codex** ```bash pluck init --target codex --mode strong # MCP + AGENTS.md pluck-first 정책 ``` **Cursor** ```bash pluck init --target cursor --mode strong # MCP + always-apply Cursor rule ``` ## 왜 pluck을 써야 할까요? AI 에이전트가 기존의 `cat`이나 `grep`으로 코드를 탐색하면 정말 많은 토큰을 낭비하게 돼요. 같은 코드를 반복해서 읽거나, 상관없는 함수까지 스크롤하고, 똑같은 import 구문을 매번 읽다 보면 한 세션에서만 수천 개의 토큰이 버려지거든요. `pluck`은 에이전트를 위한 전용 코드 검색 계층을 제공해서 이 문제를 해결해요. 핵심은 **에이전트가 코드를 검색할 때 무조건 `pluck`을 기본으로 사용하게 만드는 것**이에요. Bash는 `pluck`이 도와줄 수 없는 경우(예: 바이너리 파일이나 레포지토리 밖의 경로)에만 사용하는 최후의 수단이죠. - **스마트 아웃라인 (`pluck.read`)**: 1,000줄짜리 파일을 통째로 주는 대신, 시그니처와 아주 작은 helper 본문만 포함한 효율적인 아웃라인을 반환해요. 에이전트는 여기서 필요한 큰 함수 본문만 쏙쏙 골라올 수 있어요. - **세션 중복 제거 (Session Dedup)**: 에이전트가 "auth"를 검색하고 나중에 "token"을 검색했을 때 겹치는 코드가 있다면, 단 1토큰짜리 플레이스홀더(`[already-shown: ...]`)로 대체해요. 이미 에이전트가 알고 있는 내용을 반복해서 알려줄 필요는 없으니까요. - **기본적으로 무손실 (Lossless Default)**: 주석을 지우거나 타입을 없애면 에이전트의 판단력이 떨어질 수 있어요. `pluck`은 원본 바이트를 그대로 유지하고, 코드를 축약하는 기능은 원할 때만 켜서 사용할 수 있어요. - **100% 역량 보장**: 모든 pluck 도구에는 `cat`이나 `grep`과 바이트 단위로 정확히 동일하게 동작하는 `--raw` 폴백 옵션이 있어요. ## 작동 원리 pluck은 Tree-sitter를 사용해 파일을 AST 단위로 청크화해요. 에이전트가 쿼리를 보내면 BM25 (키워드)와 `model2vec` 스타일 정적 임베딩 ([`potion-code-16M`](https://huggingface.co/minishlab/potion-code-16M))을 RRF(reciprocal-rank fusion)로 결합해 청크의 순위를 매겨요. 덕분에 에이전트는 변수명을 정확히 몰라도 "결제 흐름" 같은 개념으로 검색할 수 있어요.

Architecture Overview

### 세션 중복 제거 동작

Session Dedup Flow

## MCP 툴 에이전트는 필요에 따라 특정 툴을 호출해요. Bash는 기본값이 아니라 최후의 수단(fallback)이랍니다. | 툴 (와이어명) | 대체 대상 | 사용 시점 | |---------------|-----------|-----------| | `mcp__pluck__read` | `cat` | 코드 파일 읽기 (기본은 스마트 아웃라인; `raw: true`로 설정하면 바이트 단위로 정확히 읽어와요) | | `mcp__pluck__grep` | `grep` / `rg` | 키워드 검색 (모든 ripgrep 플래그를 래핑했어요) | | `mcp__pluck__search` | — | 랭킹된 청크 검색 (BM25 + 시맨틱 RRF) | | `mcp__pluck__symbol` | `cat` + 스크롤 | 특정 함수/클래스만 쏙쏙 읽어오기 | | `mcp__pluck__peek` | — | 시그니처 + 직접 호출되는 요소(callee)만 확인 | | `mcp__pluck__expand` | 여러 번의 `cat` | 심볼 + N홉까지의 호출 체인(callee) 확인 | | `mcp__pluck__impact` | grep + 호출자마다 read | 역방향 호출 그래프 — "이 심볼을 누가 호출해?" | | `mcp__pluck__deps` | grep imports + 파일마다 read | 파일 단위 import 그래프 — "이 파일이 뭘 의존하나? / 누가 import하나?" | | `mcp__pluck__digest` | `cargo build`/`pytest`/CI 로그를 `cat`으로 파이프 | 장황한 도구 출력을 압축 (에러/패닉은 그대로, 진행 로그는 카운트로 축약) | | `mcp__pluck__plan` | 추측성 `search`/`read` 반복 | 자유 형식 task를 받아 다음 3-5 retrieval 호출 + confidence 지표 추천 | ## 독립 실행 CLI (에이전트 없이) 터미널에서 직접 pluck을 사용할 수도 있어요: ```bash pluck index . pluck search "auth flow" --repo . pluck read src/auth/login.ts # 스마트 아웃라인 pluck read src/auth/login.ts --raw # 바이트 단위 cat과 동일 ``` ## 성능 및 토큰 절감 효과 이 페이지의 모든 수치는 동결된 baseline 행 또는 실측 시나리오를 인용해요. 추정 / 희망 수치는 쓰지 않아요.

Token Savings Chart

### 게이트된 엔진 메트릭 [`benchmarks/baseline.json`](benchmarks/baseline.json)에 동결된 불변값이에요. 엔진 코어를 건드리는 모든 커밋은 `scripts/regression-gate.py`로 검사하고, tolerance를 벗어나면 빌드가 막혀요. | 메트릭 | 값 | `baseline.json`의 row | |--------|-----|-----------------------| | Chunker p50 (medium, 500줄) | **1.05 ms** | `chunker_medium_ms_p50` | | Indexer 처리량 (medium, 500 파일) | **2 747 files/s** | `indexer_files_per_sec_medium` | | 웜 검색 p50 (medium) | **0.07 ms** | `warm_search_p50_ms_medium` | | 파일 저장 → 검색 가능 p50 | **171 ms** | `freshness_p50_ms_medium` | | 세션 중복 제거 절감률 (5-쿼리 벤치) | **23 %** | `session_dedup_session_savings_pct` | | `pluck.digest` 로그 압축률 (6개 fixture 중앙값) | **71 %** | `digest_savings_pct` | ### 절감 대상 코드 읽기 토큰 절감 `pluck.read` 아웃라인 모드는 에이전트가 `cat` 비용을 그대로 내지 않게 해줘요. 파일 전체를 쏟아내는 대신 심볼 맵과 아주 작은 helper 본문만 반환하고, 에이전트는 필요한 큰 본문만 가져오면 돼요. | 읽기 워크로드 | `cat` 토큰 | `pluck.read` 토큰 | 절감률 | |---------------|-----------:|------------------:|-------:| | medium realistic (함수 5개, 약 120줄) | 929 | 116 | **88 %** | | large realistic (함수 25개, 약 600줄) | 4 549 | 556 | **88 %** | | xl realistic (함수 100개, 약 2 400줄) | 18 124 | 2 320 | **87 %** | | class (클래스 1개 + 메서드 50개) | 8 608 | 1 302 | **85 %** | 작은 파일과 `raw` 읽기는 control case예요. 바이트 단위 폴백이 목적이라 절감률이 거의 없거나 0 %인 게 정상이에요. ### 실측 단일 시나리오 토큰 절감 `fix-auth-token-expiry`: 동일한 JIRA 스타일 작업을 bash 워크플로(`rg -l` + 여러 `cat`) vs pluck 워크플로(`search` + `read` + `symbol`)로 수행. 둘 다 같은 버그를 같은 결론으로 고침: | 러너 | 사용 토큰 | 출처 | |------|-----------|------| | bash (`rg + cat`) | 1 248 | [`fix-auth-token-expiry-1778750775.json`](benchmarks/results/fix-auth-token-expiry-1778750775.json) | | **pluck** (`search + read + symbol`) | **931 (−25 %)** | 동일 파일 | `fix` / `refactor` / `explore` / `search` / `review` 시나리오 전반에 걸친 LLM-in-the-loop 측정은 v0.8.0 작업으로 잡혀 있어요. 측정되기 전엔 적지 않아요. ### 기능(Capability) 비교 | 기능 | `cat` + `grep` / `rg` | 다른 코드 검색 도구 | **pluck** | |------------|----------------------|-------------------------|-----------| | Hybrid BM25 + 시맨틱 랭킹 | ✗ | 대체로 ✓ | ✓ | | AST 수준 청크 분할 | ✗ | 대체로 ✓ | ✓ | | 영구 데몬 (MCP stdio) | — | ✗ (호출 시마다 콜드 CLI 실행) | **✓** | | 영구 디스크 인덱스 (mmap) | — | 대체로 ✗ | ✗ — 로드맵 (v0.7.0) | | 증분 재색인 (파일 감시자) | — | 대체로 ✗ | **✓ — 171 ms p50** | | **세션 범위 내 중복 제거** | — | ✗ | **✓ — 벤치 기준 23 % 절감** | | **`--raw` cat/grep 바이트 동등성** | — | ✗ | **✓** | | **기본적으로 무손실, 옵션으로 손실 모드 제공** | — | 도구마다 다름 | **✓** | | `peek` (시그니처 + 직접 호출 요소) | ✗ | ✗ | **✓** | | 단일 파일 아웃라인 (`pluck.read`) | ✗ | ✗ | **✓** | | 다중 홉 `expand` (호출 그래프) | ✗ | ✗ | **✓** | | 역방향 호출 그래프 (`impact`) | ✗ | ✗ | **✓** | | 파일 단위 import 그래프 (`deps`) | ✗ | ✗ | **✓** | | 빌드 / CI / 테스트 로그 압축 (`digest`) | ✗ | ✗ | **✓ — 중앙값 71 %** | | 탐색 추천기 (`plan`) | ✗ | ✗ | **✓** | ## 지원 포맷 pluck은 Tree-sitter로 **20개 이상의 코드·프로젝트 포맷**(현재 26개)을 AST 단위로 청킹합니다. 아래 모든 포맷은 [`crates/pluck-core/src/chunker`](crates/pluck-core/src/chunker)의 청커 단위 테스트로 검증되며, 이 목록은 [`lang.rs`](crates/pluck-core/src/chunker/lang.rs)의 `Lang` enum 그대로라 문서와 코드가 어긋날 수 없습니다. | 분류 | 포맷 | |------|------| | **언어** | Rust, TypeScript, TSX, JavaScript, Python, Go, Java, Kotlin, Swift, Ruby, PHP, C, C++ | | **웹 / 컴포넌트** | HTML, CSS, SCSS, Svelte | | **데이터 / 설정** | JSON, YAML, TOML, SQL, HCL / Terraform | | **스키마 / 문서 / 인프라** | GraphQL, Markdown, MDX, Dockerfile, Shell | 목록에 없는 포맷도 `pluck.read --raw` / `pluck.grep`로 동작하며 (`cat` / `rg`와 바이트 단위로 동일), 단지 AST 단위 청킹이 적용되지 않을 뿐입니다. ## 로드맵 - **v0.2.0**: crates.io 첫 발행, MCP 툴, 세션 중복 제거, 스마트 아웃라인, 확장된 검색 표면 — `digest`, `impact`, `deps`, `plan`. - **v0.3.0**: 자연어 리콜 품질 — 쿼리 확장, 2단계 cascade, NDCG@10 측정. - **v0.4.0**: Java + 레포 포맷 커버리지 — Java와 HTML은 반영됨; CSS/SCSS, Markdown/MDX, YAML/JSON/TOML, Dockerfile, Shell은 남아 있음. - **v0.5.0**: 시스템 + JVM 티어 — C, C++, Kotlin, SQL, Terraform/HCL. - **v0.6.0**: 앱 프레임워크 티어 — Ruby, PHP, Swift, Vue, Svelte, Astro, OpenAPI / GraphQL. - **v0.7.0**: 스케일 + 영속성 — mmap index, schema versioning, incremental embedding re-encode, memory/disk cap. - **v0.8.0**: 채택 + 관측성 — adoption counter, tool-description A/B harness, LLM-in-loop bench, 다국어 tool description. - **v0.9.0**: 워크플로우 지능 + 생태계 — JSON output, `diff`, `history`, `profile`, Aider / OpenHands / Cursor / Cline / Continue. - **v1.0.0**: 안정적인 기본 retrieval layer — stable MCP/CLI contract, benchmark dashboard, release checklist, config migration, supply-chain review. ## 라이선스 MIT — 자세한 내용은 [LICENSE](LICENSE)를 참고하세요.