MinishLab/semble

uv tool install semble
semble install  (detects Claude Code, Codex, OpenCode and lets you enable MCP server / instructions / sub-agent integrations)
uv tool upgrade semble  (upgrade)

Usage

• •CLI: `semble search "authentication flow" ./my-project` or search remote repos by git URL; `--content docs|config|all` to widen scope; `--top-k` to limit results
• •MCP: after `semble install`, agents call the `search` tool (local path or git URL) and `find_related` tool (file path + line number)
• •`semble find-related src/auth.py 42 ./my-project` for code similar to a known location
• •`semble savings` to see token usage saved across all searches; `semble clear` to remove cached indexes/stats

Key features

• ✓Fast: ~500ms index, ~1ms queries, all on CPU; no API keys, GPU, or external services
• ✓Accurate: NDCG@10 of 0.854 — on par with the 137M-param CodeRankEmbed transformer while indexing 220x faster
• ✓Token-efficient: returns only relevant chunks (~99% fewer tokens than grep+read; 97% recall at 2k tokens)
• ✓How it works: tree-sitter code-aware chunking + static Model2Vec embeddings (potion-code-16M-v2) + BM25, fused with Reciprocal Rank Fusion and code-aware reranking
• ✓Incremental re-indexing on file changes; .gitignore/.sembleignore support; local or remote (git URL) repos

Best for

Coding agents (Claude Code, Cursor, Codex, OpenCode) that need instant token-efficient code search across unfamiliar repos.

Caveats

• ⚠First use downloads the embedding model from Hugging Face and caches it (requires network access once)
• ⚠Cache/savings stored in OS cache folder (~/Library/Caches/semble/, ~/.cache/semble/, %LOCALAPPDATA%\semble\Cache) — overridable via SEMBLE_CACHE_LOCATION
• ⚠Always skips well-known non-source directories (node_modules/, .venv/, dist/, build/, __pycache__/)