Semble: Codesuche für KI-Agenten mit 98 % weniger Tokens als grep+read

Semble ist eine schnelle, tokeneffiziente Code-Suchbibliothek, die speziell für KI-Coding-Agenten wie Claude Code, Cursor, Codex und OpenCode entwickelt wurde. Sie gibt relevante Code-Schnipsel auf der Grundlage von natürlichsprachlichen oder Code-Anfragen zurück und verwendet dabei ~98% weniger Token als der typische grep+read-Ansatz.

Wie es funktioniert

Semble kombiniert statische Model2Vec-Embeddings (mit ihrem eigenen potion-code-16M-Modell) mit BM25, fusioniert über RRF und sortiert neu mit codebewussten Signalen. Alle Berechnungen laufen auf CPU – keine GPU, keine API-Schlüssel, keine externen Dienste. Die Indizierung eines durchschnittlichen Repositorys dauert ~250ms, und Suchanfragen werden in ~1.5ms auf CPU abgeschlossen.

Hauptfunktionen

• Tokeneffizient: 98% weniger Token als grep+read – gibt nur die relevanten Abschnitte zurück.
• Schnell: ~250ms zum Indizieren eines typischen Repositorys, ~1.5ms pro Suchanfrage (sehr große Repositories können länger dauern).
• Präzise: 0.854 NDCG@10 in ihrem Benchmark mit ~1250 Abfrage/Dokument-Paaren aus 63 Repositories und 19 Sprachen – 99% der besten Transformer-Konfiguration (137M Parameter) bei ~200x schnellerer Indizierung und ~10x schnelleren Suchanfragen.
• Null Konfiguration: Keine API-Schlüssel, GPU oder externen Dienste erforderlich.
• MCP-Server: Einsetzbar für Claude Code, Cursor, Codex, OpenCode und jeden MCP-kompatiblen Agenten.
• Lokal und entfernt: Übergeben Sie einen lokalen Pfad oder eine Git-URL. Indizes werden pro Sitzung zwischengespeichert und bei Dateiänderungen automatisch aktualisiert.

Installation und Einrichtung

MCP-Server (empfohlen für Agenten)

Erfordert, dass uv installiert ist. Für Claude Code:

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

Für Codex fügen Sie zu ~/.codex/config.toml hinzu:

[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]

Für OpenCode fügen Sie zu ~/.opencode/config.json hinzu:

{
  "mcp": {
    "semble": {
      "type": "local",
      "command": ["uvx", "--from", "semble[mcp]", "semble"]
    }
  }
}

Für Cursor fügen Sie zu ~/.cursor/mcp.json oder .cursor/mcp.json hinzu:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Bash-Integration (Alternative)

Installieren Sie mit pip oder uv und fügen Sie dann den Code-Such-Snippet zu AGENTS.md oder CLAUDE.md hinzu:

pip install semble
uv tool install semble

Dann in AGENTS.md:

## Code Search
Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
```bash
semble search "authentication flow" ./my-project
```

MCP-Tools

Der MCP-Server stellt zwei Tools bereit:

• search – Durchsucht eine Codebase mit einer natürlichsprachlichen oder Code-Anfrage. Übergeben Sie repo als lokalen Verzeichnispfad oder eine https://-Git-URL.
• find_related – Gibt bei Angabe eines Dateipfads und einer Zeilennummer Abschnitte zurück, die dem Code an dieser Stelle semantisch ähnlich sind.