Semble: Búsqueda de código para agentes de IA usando un 98% menos de tokens que grep+read

Semble es una biblioteca de búsqueda de código rápida y eficiente en tokens, diseñada específicamente para agentes de IA de codificación como Claude Code, Cursor, Codex y OpenCode. Devuelve fragmentos de código relevantes a partir de consultas en lenguaje natural o código, usando ~98% menos tokens que el enfoque típico de grep+read.

Cómo funciona

Semble combina embeddings estáticos Model2Vec (usando su propio modelo potion-code-16M) con BM25, fusionados mediante RRF y reordenados con señales conscientes del código. Todo el cálculo se ejecuta en CPU — sin GPU, sin claves API, sin servicios externos. Indexar un repositorio promedio toma ~250 ms, y las consultas se completan en ~1.5 ms en CPU.

Características principales

• Eficiente en tokens: 98% menos tokens que grep+read — devuelve solo los fragmentos relevantes.
• Rápido: ~250 ms para indexar un repositorio típico, ~1.5 ms por consulta (repositorios muy grandes pueden tardar más).
• Preciso: 0.854 NDCG@10 en su benchmark de ~1250 pares consulta/documento en 63 repositorios y 19 lenguajes — 99% de la mejor configuración de transformer (137M parámetros) con indexación ~200x más rápida y consultas ~10x más rápidas.
• Sin configuración: No requiere claves API, GPU ni servicios externos.
• Servidor MCP: Plug-and-play para Claude Code, Cursor, Codex, OpenCode y cualquier agente compatible con MCP.
• Local y remoto: Pasa una ruta local o una URL de git. Los índices se almacenan en caché por sesión y se actualizan automáticamente con los cambios de archivos.

Instalación y configuración

Servidor MCP (recomendado para agentes)

Requiere tener instalado uv. Para Claude Code:

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

Para Codex, añadir a ~/.codex/config.toml:

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

Para OpenCode, añadir a ~/.opencode/config.json:

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

Para Cursor, añadir a ~/.cursor/mcp.json o .cursor/mcp.json:

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

Integración con Bash (alternativa)

Instalar con pip o uv, luego agregar el fragmento de búsqueda de código a AGENTS.md o CLAUDE.md:

pip install semble
uv tool install semble

Luego en 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
```

Herramientas MCP

El servidor MCP expone dos herramientas:

• search — Busca en un código base con una consulta en lenguaje natural o código. Pasa repo como una ruta de directorio local o una URL de git https://.
• find_related — Dada una ruta de archivo y un número de línea, devuelve fragmentos semánticamente similares al código en esa ubicación.