pluck

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.