The MCP-native Code Retrieval Engine for AI Agents
0.07 ms warm search · 171 ms save → searchable · 71 % CI-log compression — every number gated by benchmarks/baseline.json
pluck is a local Rust daemon that replaces cat and grep as the default way AI agents read and search code. It exposes symbol-aware code reading and search to agents over the Model Context Protocol (MCP). Sub-millisecond warm search, AST-level chunking, and session-aware deduplication — with a --raw fallback on every tool so the agent never loses capability by defaulting to pluck.
Without pluck: ls → grep → cat file1 → cat file2 → cat file3 → ...
With pluck: pluck.plan "fix auth-token expiry" → 3-5 next-call recommendations
pluck.search "auth flow" → ranked chunks, BM25 + semantic
pluck.peek validate_token → signature + callees only
pluck.symbol validate_token → just that function's body
pluck.impact validate_token → every caller, depth-capped
pluck.deps src/auth/login.ts → forward/reverse import graph
pluck.digest < cargo-build.log → 71 % shorter, errors intact
Quickstart
Pluck is designed to be the default retrieval tool for your AI coding agents.
1. Install Pluck
# Daemon + standalone CLI from crates.io
cargo install pluck-mcp pluck-cli
# Or via Homebrew tap
brew tap hunhee98/pluck && brew install pluck
2. Add to your Agent
Claude Code
pluck init --target claude
(Alternatively, you can manually enable it via /plugin marketplace add hunhee98/pluck)
Codex
pluck init --target codex
Why pluck?
When AI agents use standard cat and grep to explore a codebase, they waste massive amounts of context window tokens. Re-reading the same file chunk, scrolling past unrelated functions, and re-paying tokens for identical imports on every read adds up to thousands of wasted tokens per session.
pluck solves this by providing an agent-facing layer for code search. Its core principle: every retrieval call an agent makes should default to pluck. Bash is only the fallback when pluck legitimately can't help (e.g., binary files, paths outside the repo).
- Smart Outline (
pluck.read): Instead of dumping a 1,000-line file, it returns a token-efficient outline of signatures. The agent can then fetch only the function bodies it needs.
- Session Dedup: If an agent searches for "auth" and later searches for "token", any overlapping code chunks are replaced with a 1-token placeholder (
[already-shown: ...]). The bytes are already in the agent's context; repeating them is pure waste.
- Lossless Default: Stripping comments or dropping types hurts the agent's decision-making. pluck keeps the original bytes intact and makes lossy modes strictly opt-in.
- 100% Capability Guarantee: Every pluck tool has a
--raw fallback that behaves exactly like cat or grep byte-for-byte.
How it works
pluck chunks files at the Abstract Syntax Tree (AST) level using Tree-sitter. When an agent queries, pluck ranks these chunks using a hybrid of keyword matching (BM25F over symbol/signature/content) and semantic similarity (a static model2vec-style lookup, potion-code-16M, ~60 MB on disk — no transformer inference at runtime). The two rankings fuse via reciprocal-rank fusion. This means agents can search by concept ("payment flow") rather than guessing exact variable names.
