Local code search for AI coding agents. Six fast, purpose-built tools that hand Claude Code, Codex & friends ranked answers, not raw grep. Zero API keys, 100% on-device.

Maybe grep isn't all you need… 🍬
Every coding agent today reaches for grep + Read by reflex. sweet-search challenges the narrative. 😎

✨ Highlights

• Hybrid retrieval — one of the six tools uses BM25F lexical + dense semantic + structural graph signals, fused per query and reranked by late-interaction
• Agent-native by design — token-budgeted output tiers, an optional MCP server (and default zero-overhead CLI), and a GEPA-evolved system prompt — one init installs it into Claude Code by default (Codex, Gemini CLI, and Cursor via flags)
• Indexed grep, ~10× faster than ripgrep — a sparse n-gram prefilter skips the files that provably can't match
• ColBERT-style reranking, locally — per-token MaxSim late interaction on hand-written SIMD kernels
• GPU-accelerated indexing — Apple Metal, CUDA, CoreML Neural Engine, or plain CPU via ORT; same engine, auto-selected
• Never stale — incremental indexing keeps the index aligned with your working tree, uncommitted edits included
• No storage hassle — indexed artifacts maximally optimized without any accuracy tradeoff; up to INT4 quantization
• Local-first — all models run on-device; nothing is sent anywhere, ever. CPU-inference supported for all models

📚 Table of Contents

🚀 Quickstart

Requirements: Node.js 18+ on macOS (Apple silicon or Intel) or Linux (x64 or ARM64). On Windows, run sweet-search inside WSL2.

npm install -g sweet-search

cd your-repo
sweet-search init     # one-time: downloads local models, wires up your agent
sweet-search index    # builds the index — GPU-accelerated where available

sweet-search "where do we validate JWT tokens?"

That's it. init is idempotent and SHA256-verifies every model binary; re-running it is always safe. From then on, the index stays up to date automatically as you work.

npm install -g sweet-search --allow-scripts=sweet-search,better-sqlite3

"allowScripts": { "sweet-search": true, "better-sqlite3": true }

For Claude Code, init automatically installs and activates the sweet-search output style, which adds the compact routing override at system-prompt priority. Start a new Claude session or run /clear after init, and keep that output style selected for reliable ss-* routing.

To uninstall 😢:

sweet-search uninstall --keep-models  # current repo only; keeps shared models and the global CLI
sweet-search uninstall                # current repo plus its shared model downloads; keeps the global CLI
npm uninstall -g sweet-search         # global CLI only; does not clean initialized repos

Run sweet-search uninstall inside each initialized repo before removing the global CLI.

sweet-search init --wizard          # interactive: shows your hardware, recommends a model tier
sweet-search init --profile core    # lexical-only, no model downloads (CI-friendly)
sweet-search init --li-model edge   # compact late-interaction model for constrained machines
sweet-search init --agents          # also configure AGENTS.md for Codex/OpenCode
sweet-search init --no-claude --agents # streamlined AGENTS-only configuration
sweet-search uninstall --dry-run    # preview cleanup for the current repo

📊 Benchmarks

We measure sweet-search four ways — from how much it helps a real agent down to raw engine throughput:

🤖 1. Code-retrieval benchmarks — the agent-in-the-loop test

One variable changes: how the agent searches a real repository.

• 🍬 sweet-search: the model gets our GEPA-evolved search discipline and search tools.
• 🐌 Native: the same model uses its built-in grep-and-read loop.

Same tasks, same judge, paired probe-for-probe.

_{sealed vault · exact paired results · five representative profiles · full 11-cell matrix and held-out/OOD replication below}

The headline, in four claims:

• 💰 Cheaper where the agent thrashes — up to −34% realized cost on Codex; −18 to −32% across the GPT-5.5 / opencode / bare-API harnesses.
• 🔧 Fewer round-trips — up to −56% tool calls, significant on 9 of 11 cells.
• ✨ More useful per response — +0.18 to +0.31 on a 5-dimension usefulness score, and still denser when length-matched (significant on 8 of 11 cells).
• 🎯 Accuracy held — and lifted on the weak — a statistical tie on flagship models (saturated at 0.94–0.99), and +3 pp (up to +8 pp out-of-distribution) on weaker models like GLM-5.1 and DeepSeek.

🚧 2. Task-completion benchmarks — coming soon

Retrieval quality is necessary but not sufficient. Cheaper, denser context only matters if it compounds across a real, multi-step engineering task — finding the code, understanding it, changing it, and not breaking anything. The next suite measures exactly that: resolve-rate on SWE-bench-style multi-file tasks, sweet-search-wired vs. native, on the same paired, multiplicity-controlled bar as above. Harness and pilot are in progress — numbers land here when they clear that bar, and not before.

📄 3. Paper-type retrieval benchmarks — academic NL→code IR

Every number below is the ss-search pipeline end-to-end — the same binary you install — run against the full benchmark corpus (no 99-distractor shortcuts), zero-shot (we never fine-tune on these tasks). Where a benchmark's queries are docstrings, we strip the docstring out of the indexed code so the query can't trivially match itself — the standard retrieval protocol.

We're SOTA in June 2026 on 3/4 attempted benchmarks at HARDER settings (running on full pool) than most other attempts!

_{SOTA = best result we can find in the published literature as of June 2026; cross-metric/protocol comparisons are spelled out per benchmark below.}

🌐 GenCodeSearchNet → 86.6  ·  🏆 SOTA in June 2026

• The BEST PUBLISHED number we can find, anywhere
• The benchmark's own paper caps at MRR ≤ 0.42 for fine-tuned baselines (≤ 0.10 cross-lingual); even zero-shot OpenAI Ada-2 reaches 0.79–0.94 — but all of it against a tiny 99-distractor pool.
• We score 0.866 against the entire 6,000-document corpus — a strictly harder setting — and zero-shot. 🔥

🐍 CoSQA → 65.5  ·  🥇 Zero-shot SOTA in June 2026

• Beats EVERY PUBLISHED zero-shot model
• Canonical setup: 500 real web queries → the fixed 6,267-code database, no fine-tuning.
• Clears the strongest zero-shot results out there — CodeSage-Large 47.5 · OpenAI text-embedding-3-large 55.4 · OASIS 55.8 — and goes toe-to-toe with fine-tuned CodeBERT / GraphCodeBERT (64.7 / 67.5). 💪
• _{CoSQA has known label noise, so we read the absolute height with a pinch of salt.}

🗺️ M2CRB → 54.0  ·  🏆 SOTA in June 2026

• the BEST PUBLISHED number we can find, anywhere — and zero-shot
• 🇪🇸 Spanish · 🇵🇹 Portuguese · 🇩🇪 German · 🇫🇷 French → Python / Java / JavaScript.
• The paper's best — a CodeBERT fine-tuned on the task — reaches 52.7 auMRRc, a metric that averages over easier, smaller pools (so auMRRc ≥ full-pool MRR for any model). Our 54.0 is full-pool MRR@10 over all 5,795 functions in one pool — a strictly harder measure, cleared with no fine-tuning. 🔥

🛡️ AdvTest → 51.4  ·  🧪 our honest worst case — and we publish it anyway

• Adversarial obfuscation (def Func(arg_0):) deletes the lexical + graph signals our hybrid feeds on — yet we still beat the classic fine-tuned baselines (CodeBERT 27 · GraphCodeBERT 35 · UniXcoder 41), and our stack still lifts our own encoder ~3pp even here.
• 🔍 Full transparency: we could not reproduce the often-cited 59.5 for the bare CodeRankEmbed encoder — the reference FP32 model scores 54.7 on our leak-free corpus, our shipped INT8 build 51.4. The gap is stricter preprocessing + INT8 quantization, not the retrieval pipeline. We report exactly what we measured.

⚡ 4. Engine speed — systems benchmarks, measured in-repo

🧭 Where sweet-search Fits

Code search is a crowded space. Here's an honest read on where sweet-search wins and where it gives ground, against the trending leaders and our closest local peers.

_{✅ yes · ⚠️ partial / with caveats · ❌ no. Verified June 2026; capabilities drift.
¹ claude-context's local path (Milvus Lite + Ollama embeddings) needs no API key, but it defaults to OpenAI/Voyage embeddings + Zilliz Cloud — and still runs Milvus + Ollama either way. ² Cursor's index is editor-locked — external terminal agents can't query it. ³ Reports token-reduction / efficiency, not a public NL→code retrieval-quality leaderboard. ⁴ Runs on Windows via WSL2. ⁵ SocratiCode manages a bundled Qdrant for you, but uses an auto-detected Ollama for local embeddings. ⁶ Ships an interactive HTML graph viewer, but doesn't edit code. ⁷ Cursor's local Instant Grep — a literal + regex index it benchmarks at ripgrep 16.8 s → 13 ms (the post that inspired our own n-gram prefilter). ⁸ SocratiCode runs on Windows via Docker only — no native binary, and no GPU there.}

Where we lose, plainly: no native Windows yet, no editor GUI, and we index one repo at a time. If you need org-wide search across many repos and branches, that's where SocratiCode and Sourcegraph are built to win. If you live inside one editor, Cursor's index is already there. sweet-search is for the terminal agent that wants the best local retrieval on the repo in front of it. No one else combines all of it: ColBERT late-interaction reranking and faster-than-grep search, fully on-device, with nothing to sign up for.

_{Also in the space: Sourcegraph/Cody (org-scale, server-based), Continue.dev (local-default RAG), Serena (LSP symbol search, no embeddings), grepai (local CLI + trace), and cocoindex-code (embedded AST search).}

🧰 The Six Tools

Six small tools, one shared index. Each returns ranked, deduplicated, token-budgeted output designed to be consumed by an agent — a useful answer, not a wall of matches to scroll through.

1. 🔍 ss-search — hybrid search powerhouse

A hybrid search pipeline with late interaction reranking that returns actual code blocks.

Leading published-benchmark results — strongest we can find on GenCodeSearchNet, and above every published zero-shot model on CoSQA. See benchmarks.

flowchart TD
    Q(["🔍  natural-language query"]) --> ROUTE{{"🧭 WASM CatBoost router · lexical / hybrid"}}

    ROUTE --> BM["📑 <b>BM25F</b><br/>field-weighted FTS5"]
    ROUTE --> ANN

    subgraph ANN ["🧬 three-stage ANN cascade"]
        direction LR
        BIN["binary <b>HNSW</b><br/>Hamming · ~100µs"] --> INT["INT8<br/>rescore"] --> FL["float32<br/>mmap sidecar"]
    end

    BM  --> FUSE
    ANN --> FUSE
    FUSE["🔀 <b>CCFusion</b><br/>convex combo · RRF fallback"] --> ROW1

    subgraph ROW1 [" "]
        direction LR
        IAR["⚓ <b>IAR</b><br/>exact-symbol injection"] --> INTENT["🎯 intent rerank<br/>demote docs · tests · config"]
    end

    ROW1 --> ROW2

    subgraph ROW2 [" "]
        direction LR
        GRAPH["🕸️ graph expansion<br/>typed edges · 1–2 hops · <b>PathRAG</b>"] --> MAXSIM["🧮 <b>Late-Interaction Rerank</b><br/>⚡ native Rust MaxSim kernel"] --> OUT(["🏁 <b>self-contained code blocks</b><br/>whole functions · 3k/8k/12k budget"])
    end

    classDef io    fill:#fde68a,stroke:#f59e0b,color:#000;
    classDef out   fill:#bbf7d0,stroke:#15803d,color:#000,stroke-width:3px;
    classDef route fill:#e0e7ff,stroke:#818cf8,color:#000;
    classDef lex   fill:#dbeafe,stroke:#60a5fa,color:#000;
    classDef fuse  fill:#f3e8ff,stroke:#c084fc,color:#000;
    classDef rank  fill:#ffe4e6,stroke:#fb7185,color:#000;

    class Q io;
    class OUT out;
    class ROUTE route;
    class BM,BIN,INT,FL lex;
    class FUSE,IAR fuse;
    class INTENT,GRAPH,MAXSIM rank;

    style ANN  fill:#eff6ff,stroke:#93c5fd,color:#000;
    style ROW1 fill:none,stroke:none;
    style ROW2 fill:none,stroke:none;

_{↑ The diagram traces the hybrid route. A pure-lexical query — or a literal file path — short-circuits at the router straight to BM25F, skipping the vector cascade and fusion.}

2. ⚡ ss-grep — grep, minus every wasted millisecond

10.2× faster than ripgrep end-to-end at the median — measured across 353 realistic queries on 5 real repos (range 8.5–17.7× per repo, 1 ms p50), with identical match counts on every single query. Three things buy that:

• A sparse n-gram index (inspired by Cursor's fast-regex-search and GitHub's Blackbird): instead of a fixed trigram table, gram boundaries adapt to your codebase's character-pair frequencies, so common trigrams get absorbed into longer, more selective grams.
• Regex-AST literal extraction + SIMD intersection: required substrings are pulled from the pattern's syntax tree, posting lists are intersected with NEON/SSE2 block merges (galloping search for skewed sizes), and only the files that can match — typically 0.1–5% of the corpus — see the real regex.
• Fully in-process: verification runs on Rust's regex crate with Rayon across all cores, inside the warm daemon, in a single NAPI call. No child process is ever spawned — zero fork/exec, zero pipe I/O, zero JSON re-parsing.

Every match comes back in stable file:line order — ripgrep-identical counts, optional context lines — with no relevance guessing, no subprocess, in one warm call.

3. ss-find — ColGrep, on a faster engine

ss-find "token refresh logic" --regex "refresh.*[Tt]oken"

Inspired by LightOn's ColGrep — regex precision, semantically ranked — but rebuilt on our own substrate:

• The regex stage runs on the same indexed sparse-gram engine as ss-grep (in-process, no subprocess), not a filesystem scan.
• The ranking stage scores candidates with per-token MaxSim over pre-indexed late-interaction embeddings — no model inference over documents at query time — on our custom kernels: native Rust + Rayon takes a 231-candidate MaxSim pass from 1.26 s down to 27 ms (WASM SIMD fallback at 16×).
• Regex tokens are merged into the semantic query, so the ranking sees both what you typed and what you matched.
• Like ss-search, it answers with ranked, self-contained code snippets — not bare file:line — so the find and the read collapse into one tool call. In our 30-question agent-workflow eval that eliminated every follow-up read and cut tokens 25.4% vs a grep + read workflow, at quality parity (gap of 0.01 on a 5-point scale).
• On the 60-query pattern benchmark, MaxSim ranking lifts MRR@10 to 0.45 vs 0.11 for raw grep ordering — 4× more likely the right hit lands on top.

4. ss-semantic — hybrid retrieval, scoped to one file

ss-semantic src/auth/session.ts "where does the cookie get its expiry?"

You know the file; this finds the lines. Every indexed chunk of the file is scored by three independent signals — BM25-style lexical term match, exact symbol-name match (weighted 1.5×), and per-token MaxSim late interaction over the LateOn-Code embeddings — fused with Reciprocal Rank Fusion (k=60), with symbol-less fragment chunks demoted 0.85× so real definitions win ties. The top spans are then re-read from disk (±2 context lines, overlapping spans merged), so the answer is filesystem ground truth even mid-edit; if the file is newer than its index entry you get an explicit staleness warning.

The useful answer: just the relevant spans with line numbers — not the whole file through your context window.

5. ss-trace — graph algorithms, not grep guesswork

ss-trace processOrder --in src/orders/service.py

One call returns a symbol's callers, callees, and transitive impact paths from the AST-derived code graph (entities + typed calls/imports/extends/uses edges, persisted in SQLite at index time). Ranking fuses three signals:

• Query-time Personalized PageRank via Forward Push — a local algorithm that spreads mass directionally from your target symbol and touches only the neighborhood it reaches, never the whole graph;
• Index-time edge-weighted global PageRank (damping 0.85), precomputed into a page_rank column — a function called from five sites carries five units of mass, and it costs zero at query time;
• Structural heuristics — relationship type, depth, exported-API status, fan-in — with penalties for test-only and external paths.

Because the graph is prebuilt, the global ranking is precomputed, and the personalized walk is local, a full three-section trace costs milliseconds. The relation word (callers / callees / impact) re-weights how the response token budget is split; --in disambiguates duplicate names; --depth bounds impact traversal (1–4).

6. ss-read — exact bytes, with the index's knowledge attached

ss-read src/db/pool.js 120 180

A read tool that is filesystem-grounded by construction: bytes come straight from disk (never from the index, so never stale), but each indexed file arrives annotated with its cAST chunk metadata — symbol name, entity type, signature, line span — joined from the AST chunk index. The agent gets the code and the structural map of what it's looking at in one call: cite, navigate, or trace next without another search.

The ss-* wrappers ship in the npm package and are what the installed agent prompt drives. Every capability is equally available as sweet-search CLI subcommands and as MCP tools — see Works With Your Agent.

🧠 An Agent Prompt That Was Evolved, Not Written

Shipping six tools is easy. Getting an agent to stop grepping in circles is the hard part.

So sweet-search init installs a ~1k-token system prompt that we didn't write — we grew it. A GEPA-style loop mutated candidate prompts, scored each on a dual Pareto front (accuracy × cost) against two different production agents at once — Claude Code (Sonnet) and Codex (GPT-5.5) — kept the survivors, and repeated. A final correctness pass hardened the winner. ~1k tokens, one job: teach the agent to search well.

🎓 The six rules it encodes:

🧾 The receipts — held-out discipline throughout: a dev set to iterate on, a held-out set touched only at milestones, a sealed vault opened exactly once.

⚡ GPU-Accelerated Indexing, Fully Local

Chunk → enrich → embed → quantize — every step on-device and in Rust. Batches are sized to your CPU's actual cache, two open code-models do the encoding, and two separate quantizations make the index both faster to build and small enough to live in RAM. Zero API keys; nothing ever leaves the machine.

The inference engine, picked for your silicon:

🧩 Chunking — every chunk is whole code, never a fixed window

• cAST structure-aware chunking over real tree-sitter ASTs: a recursive split-then-merge greedily packs sibling AST nodes up to the size cap and recurses into nodes too big to fit. So a chunk is always a function, a class, or a contiguous run of declarations — never a body cut in half, never a string split mid-literal.
• 14 languages get true AST grammars — JS · TS · TSX · Python · Go · Rust · Java · C · C++ · Ruby · PHP · Kotlin · Swift · C# — and a 39-config regex registry carries structure-aware chunking to 70+ more extensions.

🏷️ Metadata — context the encoder can actually see

• Every chunk ships its symbol name · entity type · signature · line span — the metadata that powers the code graph, ss-read annotations, and the self-contained answers everywhere else.
• Contextual enrichment: before embedding, each chunk is prefixed with a structured preamble assembled from the AST + code graph — file path · enclosing-scope breadcrumb · name & type · merged siblings · the imports it actually uses. Both encoders see it, so a bare getId() still retrieves on the class and module around it.
• Our nod to Anthropic's Contextual Retrieval — except they prepend an LLM-generated summary (one model call per chunk); we derive the context deterministically from structure: no LLM, no per-chunk inference, regenerated for free on every reindex. Tuned per language from GenCodeSearchNet ablations — Python stays minimal, the Java family keeps a slug-stripped path, JS/Ruby/Go/C/C++/Rust get the full preamble where closures and imports earn their keep.

🧠 Cache-aware batching — we read your CPU before we batch it

• We detect your last-level cache at runtime — hw.perflevel0.l2cachesize (the 16 MB P-cluster on Apple Silicon, not the smaller E-cluster), Intel L3, or /sys/.../cache on Linux — then size every embedding batch so one transformer layer's weights plus the batch's activations stay resident in cache. No spilling to main memory mid-layer; on a long-sequence tail that's the difference between B=1 and a measured 2.1× per-chunk slowdown.
• Uses every core the hardware really has — full count on ARM/Apple Silicon; x86 SMT siblings discounted because they don't scale inference linearly.
• ORT drives the CPU path (ONNX Runtime); GPU hosts swap in fused kernels (below). Either way inference runs off the event loop as a napi AsyncTask, so tokenization and SQLite writes overlap compute instead of stalling behind it.

🗜️ Two quantizations — one buys speed, one buys size

🤖 Two models — both open, both local, both code-specialized

• CodeRankEmbed — 768-d dense bi-encoder (137M, Apache-2.0) for first-stage recall.
• LateOn-Code — ModernBERT per-token late interaction (149M) for the rerank.
• Edge fallback for leaner machines: a 17M edge LateOn-Code (~9× smaller FP32 backbone) auto-selects on low-RAM hosts, and the whole CPU path runs INT8 with no GPU weights ever downloaded — full local search on a laptop with no accelerator.

🔄 An Index That Never Goes Stale

Most code indexes rot the moment you start typing. sweet-search ships a reconcile daemon that keeps every tier of the index converged with your working tree — uncommitted edits included — without you ever running a command.

• Save → searchable at the next reconcile tick — auto-tuned per machine between 15 s and 300 s, typically 15–60 s on a warm, idle box
• Tracks the filesystem, not git — unstaged and uncommitted changes are first-class; deleted or newly-gitignored files disappear from results automatically
• Atomic by construction — every tick publishes all five index tiers (float HNSW, binary HNSW, late-interaction segments, sparse-gram, code graph) through a single fsync-renamed epoch manifest, so a query never sees a half-updated index
• No-op edits cost almost nothing — content hashing collapses byte-identical rewrites and editor touch events into skipped re-encoding work

🦀 The Native Engine Room

Four Rust crates do the heavy lifting, each with a graceful fallback so the engine runs everywhere:

🗜️ INT4 binary segments: the on-disk format behind the RAM-sized index

The quantization headline lives up in indexing — 1.34 GiB → ~396 MiB, INT4-halved again. Here's the SSLX segment format that delivers it: crash-safe by construction, and the three-stage retrieval it feeds at query time.

🔌 Works With Your Agent

sweet-search meets your agent wherever it is — shell tools, MCP, or injected instructions:

// .mcp.json (project root) — that's the whole integration
// or just run: sweet-search init --mcp
{
  "mcpServers": {
    "sweet-search": {
      "command": "npx",
      "args": ["-y", "sweet-search-mcp", "--project-root", "/absolute/path/to/your/repo"]
    }
  }
}

• MCP server — 8 tools (search, trace, read, read-semantic, index, health, repo-map, vocab-prewarm), 2 resources, 2 prompts; all search tools declared read-only and idempotent
• Harness injection — Claude Code gets the canonical guide through .claude/rules/sweet-search.md plus an automatically selected output style; Codex/OpenCode use AGENTS.md (--agents or --codex), while Gemini (--gemini) and Cursor (--cursor) use their native project files
• Repo maps for sub-agents — the repo-map tool returns a PageRank-ranked symbol overview squeezed into any token budget, perfect for briefing a delegated agent
• Warm from the first query — a SessionStart hook pre-launches the search daemon so models, vocabulary, and indexes are loaded before you ask anything

🖥️ Platform Support

Native binaries are selected automatically at npm install time via optionalDependencies — no flags, no postinstall scripts to debug. Every native fast path has a WASM or JS fallback that produces the same results.

🙏 Prior Art & Acknowledgements

sweet-search stands on a lot of shoulders, and we'd rather name them than pretend otherwise:

• ColBERT (Khattab & Zaharia) — late interaction; LightOn for the LateOn-Code models and the ColGrep concept our pattern mode parallels
• ripgrep (BurntSushi) — the bar for grep, and our verification baseline
• GitHub's Blackbird — the sparse n-gram indexing idea we tuned per-codebase
• candle & MLX — Rust ML and the fused SDPA kernels we build on; HuggingFace tokenizers
• Aider — the repo-map idea, here rebuilt on a real knowledge graph
• USearch — memory-mapped HNSW; Malkov & Yashunin for HNSW itself
• CatBoost — the query router model; Traag et al. for the Leiden algorithm; Cormack et al. for RRF; PathRAG for flow-pruned graph expansion; cAST for structure-aware chunking
• GEPA — the reflective evolutionary prompt-optimization paradigm behind our agent prompt
• nomic-ai — the CodeRankEmbed embedding model
• Anthropic — the Contextual Retrieval idea behind our chunk enrichment, here derived from code structure instead of an LLM summary

📄 License

Apache-2.0 © PanonIT

Found it useful?

If sweet-search saves your agent's tokens, a ⭐ helps other agents' humans find it.