Semble: Busca de Código para Agentes de IA Usando 98% Menos Tokens que grep+read

Semble é uma biblioteca rápida e eficiente em tokens para busca de código, criada especificamente para agentes de IA como Claude Code, Cursor, Codex e OpenCode. Ela retorna trechos de código relevantes a partir de consultas em linguagem natural ou código, usando ~98% menos tokens do que a abordagem típica de grep+read.

Como Funciona

Semble combina embeddings estáticos Model2Vec (usando seu próprio modelo potion-code-16M) com BM25, fundidos via RRF e reordenados com sinais específicos de código. Toda a computação roda em CPU — sem GPU, sem chaves de API, sem serviços externos. Indexar um repositório médio leva ~250ms, e as consultas são concluídas em ~1.5ms em CPU.

Principais Características

• Eficiente em tokens: 98% menos tokens do que grep+read — retorna apenas os trechos relevantes.
• Rápido: ~250ms para indexar um repositório típico, ~1.5ms por consulta (repositórios muito grandes podem demorar mais).
• Preciso: 0.854 NDCG@10 em seu benchmark de ~1250 pares consulta/documento em 63 repositórios e 19 linguagens — 99% da melhor configuração de transformer (137M parâmetros) com indexação ~200x mais rápida e consultas ~10x mais rápidas.
• Zero configuração: Sem necessidade de chaves de API, GPU ou serviços externos.
• Servidor MCP: Integração direta com Claude Code, Cursor, Codex, OpenCode e qualquer agente compatível com MCP.
• Local e remoto: Passe um caminho local ou uma URL git. Os índices são armazenados em cache por sessão e atualizados automaticamente em alterações de arquivos.

Instalação e Configuração

Servidor MCP (recomendado para agentes)

Requer uv instalado. Para Claude Code:

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

Para Codex, adicione em ~/.codex/config.toml:

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

Para OpenCode, adicione em ~/.opencode/config.json:

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

Para Cursor, adicione em ~/.cursor/mcp.json ou .cursor/mcp.json:

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

Integração Bash (alternativa)

Instale com pip ou uv e adicione o trecho de busca de código em AGENTS.md ou CLAUDE.md:

pip install semble
uv tool install semble

Depois, em AGENTS.md:

## Busca de Código
Use `semble search` para encontrar código descrevendo o que ele faz ou nomeando um símbolo/identificador, em vez de grep:
```bash
semble search "fluxo de autenticação" ./meu-projeto
```

Ferramentas MCP

O servidor MCP expõe duas ferramentas:

• search — Busca em um código-fonte com uma consulta em linguagem natural ou código. Passe repo como um caminho de diretório local ou uma URL git https://.
• find_related — Dado um caminho de arquivo e número de linha, retorna trechos semanticamente semelhantes ao código naquela localização.