# Semble

> Code search library and MCP server that returns exact code snippets to coding agents on CPU without API keys or GPUs.

Semble is an open-source code search library from MinishLab, built for coding agents. It returns the relevant code snippets for a natural-language or code query, so agents do not need to grep and read whole files. It runs on CPU with no API keys, GPU, or external services, and can be used as an MCP server, a CLI tool via AGENTS.md, or a dedicated sub-agent.

## What It Is

Semble is a code search tool for AI coding agents such as Claude Code, Cursor, Codex, and OpenCode. An agent asks a question like "How is authentication handled?" and gets back only the matching code chunks. The project says this uses about 99% fewer tokens than grep+read, and that indexing and search for most repos finish in under a second. It can search a local path or a git URL, or several repos together as one corpus.

## Setup and Interfaces

Install it with `uv tool install semble`, then run `semble install`. The installer detects supported coding agents and lets you enable the MCP server, CLI instructions in AGENTS.md or CLAUDE.md, and a dedicated `semble-search` sub-agent. `semble uninstall` reverses the setup. The MCP server exposes two tools:

- `search` takes a query and a repo, with content types `code`, `docs`, `config`, or `all`.
- `find_related` takes a file path and line number and returns semantically similar chunks.

Semble also ships as a standalone CLI with `search`, `find-related`, `savings`, and `clear` commands, and as a Python library via `SembleIndex`.

## How Retrieval Works

Files are split into code-aware chunks with tree-sitter. Each query is scored by two retrievers: static Model2Vec embeddings (the potion-code-16M-v2 model) for semantic similarity, and BM25 for lexical matches. The results are fused with Reciprocal Rank Fusion and then reranked with these signals:

- adaptive weighting for symbol-like queries
- definition boosts
- identifier stem matching
- file coherence
- noise penalties for tests, shims, examples, and `.d.ts` stubs

Because the embedding model is static, no transformer forward pass runs at query time. Indexes are cached to disk and updated incrementally as files change. A custom Model2Vec-compatible model can be set with `SEMBLE_MODEL_NAME`, and `.sembleignore` controls which files are indexed.

## Benchmarks

The project reports an NDCG@10 of 0.854 across about 1,250 queries over 63 repositories in 19 languages. It states this matches a 137M-parameter code-specialized transformer while indexing about 380x faster and querying about 17x faster.

## Features
- Code search for coding agents with natural-language or code queries
- MCP server with search and find_related tools
- Standalone CLI and Python library
- Interactive installer for MCP, AGENTS.md instructions, and sub-agent
- Code-aware chunking with tree-sitter
- Hybrid semantic (Model2Vec) and BM25 retrieval with RRF fusion
- Code-aware reranking signals
- Incremental cached indexes refreshed on file changes
- Search local paths, git URLs, or multiple repos together
- Search code, docs, config, or all content
- Custom Model2Vec-compatible model support
- Token savings statistics
- Runs on CPU without API keys or GPU

## Integrations
Claude Code, Cursor, Codex, OpenCode, Gemini CLI, VS Code, Model Context Protocol, Hugging Face, uv

## Platforms
WINDOWS, MACOS, LINUX, API, VSC_EXTENSION, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.6.2

## Links
- Website: https://minish.ai/packages/semble/introduction/
- Documentation: https://minish.ai/packages/semble/introduction/
- Repository: https://github.com/MinishLab/semble
- EveryDev.ai: https://www.everydev.ai/tools/semble