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 --codex           # Codex only (per-project config, nothing under .claude/)
sweet-search init --codex --opencode # Codex and opencode
sweet-search init --claude --codex  # Claude Code and Codex
sweet-search init --agents          # Claude Code plus AGENTS.md for other AGENTS.md-reading tools
sweet-search init --no-claude --agents # streamlined AGENTS-only configuration
sweet-search uninstall --dry-run    # preview cleanup for the current repo

• Footprint — models live in ~/.cache/sweet-search/models/ and run on-device only:
  • CPU-only: a few hundred MB (INT8)
  • GPU: +~1.2 GB (FP32), skipped where it wouldn't help
  • M3+ Mac: optional +~3.2 GB CoreML cascade for the Neural Engine
• Which agents — pick with flags:
  • init alone → Claude Code
  • --codex / --opencode → only those; add --claude to keep Claude Code too
  • --agents / --gemini / --cursor → also write AGENTS.md / GEMINI.md / a Cursor rule
  • Indexing, .sweet-search/ and --mcp are the same for every choice.
• Claude Code — your CLAUDE.md stays untouched; everything goes in .claude/:
  • agents/sweet-search.md: the main agent, selected in settings.json. Claude Code's own prompt without its grep-first advice, plus our guide.
  • agents/general-purpose.md, agents/Plan.md: replace the built-in subagents; Explore is denied.
  • rules/sweet-search.md: a short reminder, gitignored (it names your local memory folder).
  • the /sweet-index skill.
  • Start a new session after init.
  • Already chose another main agent? init keeps it, puts the full guide in rules/ plus the sweet-search output style, and warns.
• Codex — our guide and tested base instructions in .codex/config.toml:
  • Codex ignores .codex/ until you trust the project; init tells you how.
• opencode — our guide, tested prompt and a tool-description plugin in .opencode/:
  • An existing opencode.json / .jsonc is edited in place, comments kept.
• Prewarm hook (Claude Code, Codex): only with a project-local install (npm i -D sweet-search). Search works without it.
• What gets indexed: .gitignore is respected; node_modules, build dirs, minified files and files over 1 MB are skipped; add extra rules in .sweet-search-ignore.

The CLI is the default contact surface. To also register the MCP server, run sweet-search init --mcp, or add it to .mcp.json yourself:

{
  "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 are declared read-only and idempotent.
• Repo maps for sub-agents: the repo-map tool returns a PageRank-ranked symbol overview that fits any token budget, for briefing a delegated agent.
• Vocabulary prewarm: sweet-search prewarm-vocab mines your repo's real identifiers, detects code communities (Leiden), and pre-warms all three search modes, so the first semantic query of a session is already cache-warm.
• Committed files stay portable: init never writes machine-specific absolute paths into committed settings files. All instruction injection is marker-delimited and reversible.

sweet-search uninstall removes Sweet Search's rule, main agent and subagent files with their settings entries, output style, AGENTS/GEMINI/Cursor instruction blocks, project hooks and skill, MCP registration, enforcement/reminder artifacts, and .sweet-search/ from the current repo. The shared model cache stays for your other repos. It preserves user-authored content. Generic Codex [features] hooks = true flags are left in place because other tools may share them, and an otherwise-empty settings file may remain as {}.

Each value is sweet-search minus native, relative to native, pooled over 200 questions. Brackets hold the 95% interval. Bold = significant after Benjamini–Hochberg.

📏 17 of 20 results survive multiple-comparison correction (Benjamini–Hochberg, q = 0.05). The 3 that do not: both Opus accuracy deltas (equal) and Codex tool calls (+0.6%).

_{Accuracy, sweet / native: Sonnet 0.899 / 0.879 · Opus medium 0.891 / 0.889 · Opus high 0.906 / 0.911 · opencode 0.869 / 0.893 · Codex 0.858 / 0.880. Wall time was not part of the pre-registered test family; its intervals are in the results file.}

Easy vs hard questions. The savings hold on both tiers but shrink on hard questions. Opus 5.5 high: billed cost −11.0% (easy) and −8.5% (hard). Its accuracy delta is −0.1% (easy) and −1.1% (hard), neither significant. On Codex, the billed saving is −18.2% on easy questions and 0.0% on hard ones.

Why the harnesses differ. Claude Code's native loop is already disciplined, so the gain is fewer tool calls at equal accuracy. opencode's native loop thrashes (11.2 calls per question), so the cut is large. On Codex, sweet-search sends more input tokens, but a larger share of them hit the cache, because sweet-search keeps the stock Codex prompt unchanged as the cached prefix.

• What's being compared: the installed sweet-search prompt and tools vs. the same model with only its built-in file-reading and shell-grep tools. Both arms use the same harness version (Claude Code 2.1.281, codex-cli 0.159.2, opencode 1.18.4).
• Questions: the r3 benchmark, pre-registered before any scored run. 11 public repos that we never used in development: jj (Rust), dgraph (Go), tortoise-orm (Python), typedoc (TypeScript), zipkin (Java), Ocelot (C#), plus okhttp (Kotlin), sequel (Ruby), composer (PHP), drogon (C++) and GRDB (Swift) on the hard tier. Question types: multi-hop, cross-layer, call chains, completeness, enforcement, decoys, and negatives (the asked-for thing does not exist).
• How the questions were built: agents drafted them with plain tools, not sweet-search. Two non-Claude models verified each gold fact against the code, and Opus agents audited the result. Hard questions also passed a closed-book screen: we dropped any question that models could answer without the code.
• Split: stratified by repo and question type, seed 42. We tuned on the dev split only. The held-out split (103 easy + 97 hard) ran once, at the end, and we looked at aggregates only.
• Scoring: the median of a 3-judge panel (DeepSeek-V4-flash, Gemini-3.1-flash-lite, MiniMax), graded against the gold facts.
• Cost: billed = tokens × list price, with cache reads and writes priced as billed. Without cache = every input token at the full price. That shows how much of the saving comes from caching.
• Statistics: the unit is the question (mean over 3 reps). Paired, question-clustered bootstrap stratified by tier (B = 20,000, seed 42). Benjamini–Hochberg at q = 0.05 across the pre-registered 5 cells × 4 metrics.
• Validity checks: 6,000 rollouts, 0 failed. Cache-fairness checks passed for Claude Code and Codex. opencode shows a warning because sweet-search ships a cache-key plugin and stock opencode does not. That is a product difference, so "cost without cache" is the fair comparison there (−25.4%).
• Honest caveats: (1) On Sol 6.1, sweet-search costs about 2.5–3% accuracy. (2) The Codex saving exists only with the prompt cache. (3) The index was built from one commit (65c4f20d). Commits that landed during the run did not change the text or tools the agent sees.
• Reproduction: results, intervals and the correction script are in core/prompt-optimization/data/final-run/ (HO1005-RESULTS.md, bh-heldout.mjs, questions-heldout.json). The earlier sealed-vault study on older models is in docs/PHASE7.md.

_{All figures sweet-search / native. ᵃ Claude Code is the only leg priced from a real OpenRouter invoice (10,371 generation records, 0 unresolved), sidechain-inclusive, because its rows.json nulls cost arm-asymmetrically and would reverse the sign. ᵇ Codex ran on a ChatGPT subscription, so nothing was billed — its dollars are list-price-equivalent, not an invoice. opencode is list-price ledger with 0 nulls on both arms.}

The mechanism, stated plainly. Sweet-search's main-loop spend is close to native's (−6.1% on Claude Code). The gap is delegation: native spawns subagents to explore a repo it can't navigate cheaply, and each one is a fresh context that gets billed. Better retrieval removes the reason to delegate. That's why the same product shows 31% on a harness with a subagent tier and 2% on one without — and why we quote a range, not one number.

• What's compared: the installed sweet-search agent prompt + tools vs. the same model using its built-in file-reading and shell-grep loop. The sweet-search system prompt says nothing about subagents or delegation — it only routes code search through ss-*.
• Design: 200 tasks × 2 arms × 1 rep × 3 harnesses = 1,200 rollouts. Tasks drawn from SWE-rebench V1+V2, admitted only if the official gold patch grades FULL in the exact run environment (a "green ledger" gate), and re-verified per run.
• Isolation: every rollout runs in its own mount/PID/network jail with an SNI-allowlist egress proxy — the agent can reach the model API and nothing else. No GitHub, no package registries. Escape attempts are counted, not assumed to be zero.
• Grading: the official SWE-bench/SWE-rebench Docker evaluator, FAIL_TO_PASS + PASS_TO_PASS. A patch that produces no test evidence is marked ungradeable, never scored zero. Final run: 0 ungradeable, 0 zero-call rollouts, 0 run errors across all 1,200.
• Honest caveats we keep attached: (1) 1 rep — a single cell on this bench has been observed swinging 3/3 → 1/3 → 2/3 across identical runs, so the solve column is a point estimate. (2) 37 of 199 stamped tasks (18.6%) are naming lotteries — the hidden test needs an identifier the reference patch invented, which no amount of retrieval can recover. (3) Three legs, three cost bases, only one a real invoice — do not pool the dollar figures. (4) The three solve deltas all lean the same way (−3, −6, −7); individually noise, collectively a hint that sweet-search may cost a little accuracy, and we'd rather say so than round it to zero.

• Reproduction: the result file for each headline number is in eval/results/. Rerun one with node eval/run_benchmark.js --dataset=<name> --profile=full (add --split=heldout for GenCodeSearchNet). The canonical full-pool loaders are in eval/download_data.py.
• Docstring stripping. For docstring-derived benchmarks (AdvTest, M2CRB) we strip the docstring from the indexed code. Otherwise the query matches itself verbatim: a no-strip AdvTest run scores a meaningless 0.98.
• Dev/held-out split. Ranking work iterates on a fixed, stratified dev split (seed=42); the rest is held-out and inspected aggregate-only at milestones. We did not tune ranking on CoSQA, M2CRB or AdvTest.
• What we don't claim yet. CoIR (NDCG@10 over per-subtask corpora up to ~1M docs), CoSQA+ (multi-positive, MAP-primary) and CLARC (per-group pools) use protocols our single-pool MRR@10 harness doesn't match, so we omit them.
• Honesty corner: CrossCodeEval (cross-file completion-context retrieval, a different task than NL search) sits at 0.18. We don't optimize for it and report it anyway.

• 🧠 A denser vector graph than most. Our own binary HNSW raised recall@200 from 80.6% to 86.5% and got about a third faster.
• ⚡ Native reranking. The MaxSim math runs in Rust on all CPU cores, 47× faster than plain code.
• 📦 A small index. Token vectors are packed into 4 bits, which makes that index 3.4× smaller.
• 🎛️ Quality scores. Each chunk is scored on test proximity, git recency, call-graph centrality, comments and complexity. Production code rises and old fixtures sink.
• 🛟 A reranker we switched off. We built a cross-encoder too. It was 3× slower and did not beat MaxSim, so it ships disabled.

Also available as sweet-search "<query>" on the CLI and the search MCP tool. Use --full or --xl for a bigger answer, and --mode lexical|semantic|hybrid|pattern to pick a mode. Full details: vector index · quantization.

• Each file's path prints once, with no header or legend. That cut our output by a third, with no hit or count lost.
• Method, per-repo results and the optimization log: docs/GREP_INDEXING_STRATEGY.md.
• A regex with no fixed text (for example \w+\d) cannot use the index, so it scans every indexed file.

• Ranking: on 60 pattern queries, MRR@10 is 0.45. Grep order gets 0.11, and search without the regex gets 0.30.
• Agent eval (April 2026): Claude Sonnet 4.6 answered 30 fastify questions. Versus grep + read, follow-up reads fell from 4.9 to 0 and tokens fell 25.4%, at equal quality (blind Claude Opus 4.6 judge). The prompt was tuned on these same 30 questions.
• Needs the late-interaction index, which is built by default.
• Also available as sweet-search --mode pattern and as the regex argument of the MCP search tool.
• Kernel details: docs/MAXSIM_OPTIMIZATION.md.

• Returns the top 5 spans by default. Change it with --top.
• A file that is not indexed falls back to a plain read.
• Also available as sweet-search read-semantic and as the read-semantic MCP tool.

• Add callers, callees or impact after the symbol to get only that part.
• Two symbols with the same name? Pick one with --in <file>.
• Impact paths go 3 hops deep by default. Change it with --depth (1 to 4).
• sweet-search trace and the MCP tool also return the code, in a 4k, 8k or 12k token budget.
• On very dynamic code (calls by string name, metaprogramming), the graph can miss calls.
• Also available as sweet-search trace and as the trace MCP tool.

• After the code, it names what the agent has not read yet:
  • the functions that come after the range, with their line ranges;
  • the fields and constants above the range that the code uses.
• Lines the agent already read, if unchanged, come back as a one-line reminder instead of the code.
• 10-20, 10:20 and 40 5 (5 lines from line 40) also work as ranges.
• Minified and generated files are refused.
• Set the line-number format with SS_READ_GUTTER=tab|colon|none.
• Also available as sweet-search read.

These checks ran on the step 1 prompt. None of these questions, languages or models was seen during tuning. A score of 1.00 means every question was answered correctly. For Claude Code and Codex, the score is the worse of the two agents.

[!IMPORTANT] We found a silent upstream bug that wrecked retrieval. Upstream candle-transformers masks padding with f32::MIN. Candle's Metal attention kernel downcasts that mask to F16, where it becomes -Inf, and softmax turns every padded row into NaN. Nothing crashes, but GenCodeSearchNet MRR fell to 25%. We use a -1e4 mask that survives F16.

A second one: upstream ModernBERT hardcodes an F32 mask dtype. Upstream PR #2872 fixed that in bert.rs but never ported it.

By the numbers: 5,000+ lines of Rust and Objective-C · 2 vendored models · 3 hardware backends · 18 CoreML variants

• We vendor the upstream models (NomicBERT for embeddings, ModernBERT for late interaction) and replace only the attention forward pass.
• Why: upstream attention builds the full attention matrix in every layer. On Metal, one batch took ~4.2 s, ~10% slower than the CPU path.
• Metal: a fused SDPA kernel ported from MLX.
• CUDA (Ampere+): candle-flash-attn with variable-length packing. Candle's SDPA has no CUDA backend, and the naive BF16 fallback drifted (per-token cosine down to 0.69).
• CPU: byte-for-byte upstream math, so the fallback is provably identical.

• Concurrent Metal command-buffer submissions share candle's global command queue and silently corrupt outputs.
• One process-wide lock serializes all Metal work. A GPU call takes under 10 ms, so latency stays low.

• 18 pre-traced .mlpackage variants, 6 per model, bucketed by batch size and sequence length.
• Dispatched to the Apple Neural Engine through an Objective-C shim. Oversized batches fall through to Metal.
• Gated to M3+: on M1/M2 the Neural Engine doesn't beat its own compile overhead. We measured, so it's off there.

• The preamble (path · scope chain · symbol · siblings · imports) is built at index time from a code-graph line-range overlap query. Never an LLM call.
• Routed per language family: full enriched text for JS/Ruby/Go/C-family/Rust, a slimmer path policy for Python and the Java family. Every choice was settled by per-language ablation, not a global default.

• While batch N+1 embeds, batch N's vectors stream into SQLite through zero-copy buffer views.
• Full rebuilds write to a temp file and swap atomically, so a crash never leaves you serving half an index.

Source: crates/sweet-search-native/src/inference/

By the numbers: 6 indexes · 1 atomic manifest · ≤50 files and ≤2 s of CPU per update · 4 independent memory limits

• Stable chunk IDs. Each chunk's ID comes from its symbol and signature. An edit re-embeds only the function you touched, even when every line below it shifts.
• No-op saves are nearly free. An xxHash3 content hash spots saves with no real change and skips the models.

• One atomic switch. Each update stages its writes, then publishes every index through one fsync-renamed manifest. A query pins one manifest, so it never sees a half-updated index.
• Baseline gate. The daemon never builds the first index. It checks the full indexer's fingerprint first, and waits (waiting_for_initial_index) until one exists.
• One admission policy. The full indexer and the daemon share one module that decides what gets indexed: include globs → deny list → .sweet-search-ignore → 1 MB cap → git check-ignore. The two paths cannot drift.
• Worktree-safe. A worktree stamp and a single-writer lock stop two daemons from mixing index histories.

• Orphan sweep. Deleted, newly ignored, and newly oversized files are tombstoned in every tier. The index converges to what a fresh full rebuild would produce.
• Self-maintenance. Per-tier health watermarks (tombstone fraction, stale-doc ratio, delta ratio) trigger low-priority compaction in a separate worker.

• CPU only, with at most 50 files and 2 s of CPU per update. The GPU stays free for full builds.
• Adaptive interval between 15 s and 300 s, tuned from load average, churn, and backlog.

The daemons show up in ps / Activity Monitor as sweet-search-maintainer and sweet-search-daemon. A maintainer holds roughly 2–3 GB, because the models stay loaded so updates are fast. Four independent limits keep it bounded:

A recycle or eviction never touches the index. Every update publishes before the process exits.

• sweet-search reconcile status and sweet-search reconcile inspect <path> show what the daemon thinks, and why.
• Turn it off with SWEET_SEARCH_RECONCILE_V2=0.

Want a clean slate? sweet-search index --full rebuilds from scratch at any time. After an upgrade that changes the models or chunking, we tell you to run sweet-search index, which then re-embeds everything.

_{✅ yes · ⚠️ partial / with caveats · ❌ no. Verified September 2026; capabilities drift.}

_{¹ claude-context defaults to OpenAI/Voyage embeddings + Zilliz Cloud. Its local path (Milvus Lite + Ollama) needs no API key, but still runs Milvus + Ollama.
² Graphify parses code locally with no key. Docs, PDFs and images go through your agent's model or an API key.
³ GitNexus local embeddings are opt-in (analyze --embeddings).
⁴ Semble uses static (Model2Vec) embeddings, not a transformer.
⁵ Outside this table, ColGREP (LightOn) also runs ColBERT code search locally, as a grep-style search CLI.
⁶ Reports token / cost / tool-call savings, not NL→code retrieval quality.
⁷ Graphify's code result is answer coverage on 6 questions about one repo. Its retrieval benchmarks are on chat memory (LOCOMO, LongMemEval), not code.
⁸ Semble's own set: ~1,250 queries over 63 repos, with queries and labels written by Claude Sonnet 4.6.
⁹ PolyForm Noncommercial.
¹⁰ Runs on Windows via WSL2.
¹¹ Tree-sitter grammars, config and markup formats included.
¹² Indexes each project separately; one session can query several indexed projects, with no cross-repo links.}