wigolo

---

O wigolo dá a um agente de IA uma única superfície para tudo relacionado à web: busca, fetch, crawl, extração, cache, encontrar-semelhantes, pesquisa e loops autônomos de coleta. Ele roda onde quer que seu agente rode — como um servidor MCP ao lado do seu agente de codificação, como um endpoint REST/MCP na máquina onde seus agentes self-hosted vivem, ou embutido via SDK dentro do seu próprio aplicativo. As ferramentas principais não precisam de chaves de API, nada que ele toca sai de ~/.wigolo/, e nenhuma conta cresce com o quanto seu agente pensa.

Início rápido

npx wigolo init                              # set up the local engine — any system
npx wigolo init --agents=claude-code,cursor  # …or set up + wire your day-to-day agents in one command

Requer Node ≥ 20 e cerca de 1,5 GB de espaço livre em disco no macOS, Linux ou Windows. O init puro configura o mecanismo local: ele baixa o mecanismo do navegador e os modelos no dispositivo, executa uma verificação de saúde e relata cada componente. Adicionar --agents conecta os agentes nomeados na mesma execução, então um agente de codificação que você usa diariamente fica pronto em um único comando.

• Agentes suportados — --agents aceita qualquer um de claude-code · cursor · codex · gemini-cli · opencode · vscode · windsurf · zed · antigravity (separados por vírgula); o wigolo escreve a configuração MCP e, onde suportado, instruções para cada um.
• Qualquer outra configuração — qualquer cliente MCP, framework de agente ou agente self-hosted registra npx -y wigolo na sua própria configuração MCP. O guia de instalação tem o bloco de configuração exato para cada cliente, além dos canais Docker, Homebrew e binário de arquivo único.
• Mais por vir — a lista de suportados continua crescendo, e um PR para adicionar seu agente é bem-vindo; veja CONTRIBUTING.md.
• Configuração interativa — --interactive é um fluxo de texto puro; --wizard é a TUI completa do terminal.
• Adiar downloads — --no-warmup espera até o primeiro uso. Uma falha no download de um componente nunca falha a configuração; o init relata o que não está pronto com a correção exata e ainda assim conclui.

init é não assistido por padrão, então é seguro em scripts e CI, e qualquer problema de configuração aparece aqui no relatório por componente, antes da primeira chamada do seu agente. Busca, fetch, crawl, extração, cache e encontrar-semelhantes funcionam sem chave de API. Verifique se está saudável a qualquer momento:

npx wigolo doctor

Para remover tudo de forma limpa, execute npx wigolo config --uninstall --yes. Você também pode colar o guia de instalação em qualquer assistente de IA e deixá-lo fazer a configuração; ele foi escrito para ser autossuficiente.

Recomendado — uma chave gratuita para research e agent

Busca, fetch, crawl, extração, cache e encontrar-semelhantes são totalmente sem chave. research, agent e search format=answer usam um LLM para escrever a resposta sintetizada com citações. Sem ele, eles devolvem um resumo bruto e evidências para o seu agente montar. Uma chave gratuita do Gemini transforma isso em uma resposta final:

export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<free-key>      # grab one at aistudio.google.com/apikey — the free tier is plenty

Qualquer provedor funciona (anthropic · openai · groq), ou fique totalmente local e sem chave com WIGOLO_LLM_PROVIDER=ollama (ou qualquer URL compatível com OpenAI). Defina no seu shell ou no bloco env do MCP do seu agente. Provedores, modelos e a escada de modelos locais sem chave estão no guia de configuração.

O que seu agente recebe de volta

Cada resultado de busca é uma evidência sobre a qual o agente pode agir. Ele carrega um trecho verbatim fixado na posição exata na fonte, um ID de citação que o agente pode citar e uma pontuação que ele pode inspecionar (formato real abreviado):

{
  "results": [{
    "title": "Logical replication - PostgreSQL docs",
    "url": "https://www.postgresql.org/docs/current/logical-replication.html",
    "excerpt": "Logical replication is a method of replicating data objects…",
    "citation_id": "src-1",
    "source_span": { "start": 1042, "end": 1305 },          // byte-exact provenance
    "evidence_score": { "final": 0.86, "semantic": 0.91, "lexical": 0.78, "engine_consensus": 3 }
  }],
  "citations": [{ "id": "src-1", "url": "…" }],
  "freshness_signal": { "published": "2026-05-12", "confidence": "high" }
}

Resultados fracos são sinalizados como lixo pelo próprio avaliador do wigolo. Mecanismos com falha são relatados e cache obsoleto é rotulado, então o agente sempre sabe em que está se apoiando. Contratos completos de resposta por ferramenta estão na referência de ferramentas.

Ferramentas

Ferramenta	O que faz
🔎 search	Busca web multi-mecanismo (18 adaptadores diretos) com fusão de classificação, reclassificação por ML e uma pontuação explicável por resultado. Passe um array de consultas para amplitude paralela. Escopo por domínio e intervalo de tempo, corresponda uma frase exata ou retorne resultados de imagem.
📄 fetch	Carrega uma URL através de um roteador em camadas que escala automaticamente de HTTP puro para um mecanismo de navegador headless em desafios anti-bot ou shells SPA. Markdown limpo + metadados + links. Lida com PDFs, section de cabeçalho único, sessões autenticadas e ações de página (clique / digitar / rolar / captura de tela).
🕸️ crawl	Crawl de múltiplas páginas — BFS, DFS, sitemap ou somente mapa. Limites de taxa por domínio, respeito ao robots.txt, deduplicação de conteúdo repetido.
🧩 extract	Dados estruturados de uma página: tabelas, metadados, JSON-LD, identidade de marca, esquemas nomeados (Artigo / Receita / Produto / …) ou qualquer JSON Schema personalizado.
💾 cache	Consulta tudo o que já foi visto — por palavra-chave ou semântico híbrido. Além de estatísticas, limpeza e detecção de mudanças.
🧲 find_similar	Páginas semelhantes a uma URL ou conceito, via fusão de 3 vias de palavra-chave + semântico + web ao vivo.
🧠 research	Decompõe uma pergunta → distribui sub-consultas → busca fontes → sintetiza um relatório com citações (ou um resumo estruturado que o LLM host escreve a partir dele).
🤖 agent	Loop autônomo de coleta: planejar → buscar → fetch → extrair → sintetizar, com registro de etapas, orçamento de tempo e esquema de saída opcional.
🔁 diff + ⏱️ watch	Veja exatamente o que mudou em uma página desde a última visita; verifique novamente sob demanda e entregue mudanças a um webhook.

Cada ferramenta também roda a partir do terminal (wigolo search "…" --json), de um shell interativo com pipe NDJSON (wigolo shell), via REST e através dos SDKs — referência CLI. Guias por ferramenta com o conjunto completo de parâmetros estão em docs/tools.md; exemplos executáveis estão em examples/.

Por que é diferente

O wigolo não é um substituto gratuito das ferramentas pagas — ele foi construído para igualá-las. É uma camada web focada para seus agentes: uma superfície MCP e REST que eles chamam diretamente, com a qualidade de busca e extração que os serviços pagos cobram. O que o diferencia:

• Feito para agentes. Uma única chamada MCP distribui muitas consultas por muitos mecanismos em paralelo, o que um loop serial de ferramentas do host não consegue replicar. Cada resultado carrega pontuação transparente por resultado, e a saída é consciente do orçamento.
• Saída honesta. Cache obsoleto, fetches com falha, backends degradados e truncamento são expostos no resultado. Quando uma página protegida por bot não pode ser lida, você recebe uma falha blocked_by_challenge rotulada, não um shell de desafio devolvido como conteúdo.
• $0 por consulta, livre para re-consultar. A busca padrão fala com mecanismos públicos através de adaptadores diretos; o reclassificador e os embeddings rodam no dispositivo. Cada resposta é armazenada em cache, então perguntar de novo é instantâneo e não custa nada.
• Privado por padrão. Cache, embeddings, modelos e configuração ficam em ~/.wigolo/. Nada chega a terceiros a menos que você opte explicitamente por um LLM para síntese.

Aqui está o que um resultado real parece, dissecado. Inclui o mecanismo com falha e o resultado fraco, porque essas também fazem parte da resposta:

Patrocinadores

Obrigado aos patrocinadores abaixo, que ajudam a manter o wigolo mantido e gratuito para todos usarem. O apoio deles vai direto para o trabalho.

O wigolo é gratuito para todos e pretende continuar assim. Se você ou sua empresa gostariam de ajudar a mantê-lo, há espaço para mais patrocinadores — entre em contato em ktowhid20@gmail.com, ou veja SPONSORS.md para os termos. Uma doação única via Buy Me a Coffee também é bem-vinda.

Benchmark

Todas as quatro ferramentas convergiram na mesma resposta central, e apenas uma delas devolveu evidência verbatim, fixada por byte, enquanto fazia isso.

Uma consulta fria rodou ao vivo dentro de uma única sessão Claude Fable 5, distribuída para quatro ferramentas web em pé de igualdade (WebSearch embutido, wigolo, Tavily, Exa), e foi julgada pelo agente apenas pela evidência. Todas as quatro convergiram na mesma resposta e na mesma fonte principal, então a paridade é demonstrada na tela. Apenas o wigolo retornou trechos verbatim fixados em intervalos de fonte com deslocamento de byte, uma decomposição de pontuação explicável e telemetria ao vivo por mecanismo, e seu próprio avaliador sinalizou dois resultados fracos como lixo. As ferramentas em nuvem também merecem seu lugar: a Exa renderizou a matriz de comparação dos documentos oficiais por completo. Execute sua própria consulta e você verá o mesmo formato.

Como se compara

	wigolo	Firecrawl	Exa	Tavily
Busca web multi-mecanismo	✅	✅	✅	✅
Fetch e extração estruturada	✅	✅	✅	✅
Crawl e mapa de site inteiro	✅	✅	—	✅
Trechos verbatim fixados em intervalos de fonte com deslocamento de byte	✅	—	—	—
Decomposição de pontuação explicável por resultado	✅	—	—	—
Memória local persistente — re-consulte instantaneamente, offline	✅	—	—	—
Dados de consulta permanecem na sua máquina	✅	—	—	—
Chave de API / conta	nenhuma	obrigatória	obrigatória	obrigatória
Custo por consulta	$0	medido	medido	medido

_{Status dos recursos em julho de 2026 — verifique a documentação de cada fornecedor para o estado atual.}

Essa última linha se acumula, porque agentes perguntam em rajadas:

Além do seu editor

As mesmas dez ferramentas servem a todos os tipos de agente, em qualquer superfície que se encaixe: MCP para agentes de codificação, REST para todo o resto, SDKs para embutir e wrappers de framework para integrar.

API REST — wigolo serve

Um único processo expõe uma API REST JSON puro ao lado do transporte MCP. Nenhum cliente MCP necessário, apenas curl:

wigolo serve                          # 127.0.0.1:3333 — loopback is open; off-loopback requires a token

curl -sX POST http://127.0.0.1:3333/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"local-first software","max_results":5}'

POST /v1/{tool} cobre todas as dez ferramentas, GET /openapi.json é o contrato OpenAPI 3.1, e /mcp + /sse atendem clientes MCP remotos na mesma porta. Ao vincular além do loopback, um token de portador é obrigatório, então o servidor falha de forma segura por padrão. Aponte o n8n, um assistente estilo Hermes ou qualquer agente auto-hospedado para ele. → API REST

SDKs — TypeScript e Python

Clientes finos e tipados com um modo local embutido que encontra ou inicia o daemon para você. Sem etapa separada de serve.

TypeScript — npm install wigolo-sdk (sem dependências; Node / Bun / Deno / edge):

import { createLocalClient } from 'wigolo-sdk/local';

const { client, close } = await createLocalClient();   // reuse a running daemon, or spawn one
const res = await client.search({ query: 'local-first web search', max_results: 5 });
console.log(res.results.map((r) => r.title));
await close();                                          // stops the daemon only if this call spawned it

Python — pip install wigolo (apenas biblioteca padrão; síncrono + assíncrono):

from wigolo import local_client

with local_client() as client:                          # reuse a healthy daemon, or spawn one
    res = client.search(query="local-first web search", max_results=5)
    for r in res["results"]:
        print(r["title"], r["url"])

→ SDKs e modo embutido

Integrações com frameworks

Insira as ferramentas do wigolo no framework que você já usa. Você obtém a superfície completa de dez ferramentas, incluindo cache / find_similar / research / agent que a maioria das ferramentas web de frameworks não oferece:

Framework	Pacote	O que você obtém
LangChain	wigolo-langchain	cada ferramenta como um BaseTool, além de um BaseRetriever sobre search / find_similar para RAG
CrewAI	wigolo-crewai	wigolo_tools() → entregue o conjunto a qualquer crew
LlamaIndex	wigolo-llamaindex	um BaseReader que carrega páginas buscadas / rastreadas / pesquisadas como documentos
Vercel AI SDK	wigolo-vercel-ai-sdk	fábricas de ferramentas para generateText / streamText, amigável para edge

→ Integrações com frameworks

Docker

# stdio MCP — wire it into any MCP client as command: docker
docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo

# HTTP server for remote / multi-client use
docker run -p 3333:3333 -v wigolo-data:/data \
  -e WIGOLO_API_TOKEN=a-long-random-secret \
  ghcr.io/knockoutez/wigolo serve --host 0.0.0.0

A imagem enxuta carrega modelos lentamente no volume; :full pré-instala o mecanismo do navegador. Também disponível no Docker Hub como towhid69420/wigolo. → instalação e todos os canais

Habilidades de agente

Um catálogo de habilidades com 11 itens ensina seu agente de codificação a usar bem cada ferramenta. Ele é instalado por init e gerenciado com wigolo skills add|list|remove. → habilidades

Uma observação para quem auto-hospeda: alguns sites protegidos por desafios avaliam a reputação do IP, então um IP de datacenter não atravessa barreiras que uma conexão residencial atravessaria. O wigolo rotula essas falhas, e o guia de auto-hospedagem cobre a resposta de proxy opcional.

Histórico de estrelas

Arquitetura

Um único processo Node fala MCP (JSON-RPC sobre stdio). Tudo que é pesado é local e carregado lentamente, então uma instalação sem chaves não paga nada pelas partes que não está usando.

flowchart TD
    A["🤖 AI agent<br/>any MCP client · REST · SDK"]
    A -->|MCP over stdio| B["<b>wigolo</b><br/>10 tools · dynamic instructions<br/>in-process browser pool + cache + models"]

    B --> C{"Tool layer"}
    C --> T1["search · fetch · crawl · extract"]
    C --> T2["cache · find_similar · research · agent"]

    T1 --> F["⚙️ Fetch router<br/>tiered escalation, learned per domain"]
    T1 --> S["⚙️ Search<br/>18 engines → rank fusion → ML rerank<br/><i>explainable evidence score</i>"]
    T2 --> DB[("🗄️ Local cache<br/>keyword + vector index")]
    T2 --> ML["🧠 On-device ML<br/>embeddings + reranker"]

    F -.->|optional| LLM["☁️ LLM<br/>synthesis only · opt-in"]
    S -.->|optional| SX["🔀 Aggregator backend<br/>opt-in legacy / hybrid"]

    F --> WEB["🌍 Public web"]
    S --> WEB

    style B fill:#7c3aed,stroke:#5b21b6,color:#fff
    style WEB fill:#0ea5e9,stroke:#0369a1,color:#fff
    style DB fill:#1e293b,stroke:#334155,color:#fff
    style LLM stroke-dasharray: 5 5
    style SX stroke-dasharray: 5 5

• Código supera modelo. O trabalho determinístico fica fora do LLM: canonicalização, fusão de rankings, deduplicação e correspondência de esquemas. O modelo é reservado para julgamento, opcional e limitado por solicitação. Campos preenchidos por LLM são verificados contra a fonte e anulados se ausentes.
• Roteamento orientado por sinais. A escada de busca evolui para um navegador real com base em sinais observáveis, não em suposições de domínio: marcadores de SPA, corpos de desafio, conteúdo fino. Ela aprende por domínio, desaprende quando um site deixa de precisar dela, e wigolo tune list mostra exatamente o que aprendeu.
• Lê páginas como um navegador. A busca em camadas espera desafios intersticiais e reutiliza autorizações por domínio, educadamente: robots.txt respeitado, limites de taxa por domínio, volumes de nível de pesquisa. Quando uma barreira permanece, a falha é rotulada e relatada.

Configuração

Uma instalação limpa funciona imediatamente. Três configurações elevam a qualidade da saída:

# 1. Synthesis — the biggest lever (research / agent / search-answer write real prose)
export WIGOLO_LLM_PROVIDER=gemini                   # or anthropic / openai / groq / ollama (keyless)
export GEMINI_API_KEY=<your-key>

# 2. Wider retrieval funnel
export WIGOLO_SEARCH=hybrid                         # core engines + aggregator fallback
export WIGOLO_GITHUB_TOKEN=...                      # GitHub code search 10 → 30 req/min

# 3. Land more fetches, stay warm
export WIGOLO_TLS_TIER=auto                         # per-domain learned fetch hardening
export WIGOLO_EAGER_WARMUP=1                        # pay the ~1s model load up front

Hábitos por chamada que compensam: consultas em arrays (["a","b","c"]) para amplitude paralela · search_depth: "deep" para consultas importantes · include_domains como filtro rígido para buscas em documentação. A referência completa cobre todas as variáveis de ambiente, chaves de arquivo de configuração, backends de busca, TTL de cache e limites de serviço; está no guia de configuração.

Documentação e exemplos

docs/ — o manual completo: primeiros passos · instalação e canais · configuração · referência de ferramentas · CLI e shell · API REST · SDKs e integrações · auto-hospedagem · habilidades de agente · plugins · solução de problemas e FAQ · privacidade e segurança

examples/ — executáveis, cada um com um README (e a maioria com gravação de terminal): CLI de uso único, pipelines de shell NDJSON, REST via curl, SDKs TypeScript e Python, ferramentas do Vercel AI SDK, apontando n8n auto-hospedado para um wigolo remoto, watch-com-webhook e escrevendo seu próprio plugin de mecanismo de busca. A documentação também é renderizada no site em knockoutez.github.io/wigolo/docs.

Beta e feedback

O wigolo está em beta público. Tudo documentado aqui funciona e é mantido por uma suíte de 7.600 testes; é estável, e o beta é sobre o padrão de polimento. Ele permanece em beta até que pessoas suficientes o usem, testem e deem estrela para que chamá-lo de v1 signifique algo. Seu feedback molda o que vem a seguir, e cada relato é lido, geralmente no mesmo dia:

• 🐛 Relatar um bug — quebrou, se comportou mal, surpreendeu você
• 💡 Solicitar um recurso — algo que deveria fazer
• 💬 Perguntar qualquer coisa — dúvidas, configurações, mostre e conte

Se o wigolo ganhar um lugar na sua configuração, três coisas o mantêm vivo: uma ⭐ estrela (é assim que o código aberto é encontrado), um ☕ café (não há plano pago e nunca haverá) ou um e-mail que vai direto para o único desenvolvedor que escreveu o código.

Solução de problemas

wigolo doctor nomeia qualquer componente quebrado e a variável de ambiente ou comando exato que o corrige; wigolo doctor --fix repara os casos comuns, e wigolo verify verifica a saúde de cada componente. Um componente falhando durante init não quebra o wigolo: init ainda sai com código 0, e busca / fetch / crawl / extract / cache principais funcionam sem modelos e sem navegador. Dicas rápidas:

• Downloads lentos ou com falha — execute novamente wigolo warmup --all (ou --browser / --embeddings / --reranker); eles retomam e tentam novamente.
• Navegador não inicia no Linux — wigolo warmup --browser instala as bibliotecas do SO (ou imprime o comando exato).
• Erro de build nativo / Node incomum — use um LTS: Node 20, 22 ou 24.
• Atrás de um proxy — USE_PROXY=true + PROXY_URL; adicione NODE_EXTRA_CA_CERTS para proxies que inspecionam TLS.

O guia completo cobre correções por sintoma, um mapa de "o que ainda funciona quando X falha", notas de plataforma (incluindo linux-arm64) e instalações offline: docs/troubleshooting.md.

FAQ

Grátis? Qual é o truque?

Sem truque, por design. As partes caras (ranqueamento, embeddings, o mecanismo do navegador) rodam no seu hardware, então não há custo por consulta a recuperar e nenhuma razão para um medidor. É sustentado por doações, e a licença AGPL impede legalmente uma mudança para um produto hospedado fechado.

A qualidade realmente está no mesmo nível dos serviços pagos?

A seção de benchmarks acima é uma execução ao vivo de 4 vias que você pode reproduzir: consultas cotidianas de agentes ficam em paridade, as ferramentas pagas ainda vencem alguns casos extremos de extração profunda, e o crawling é onde o wigolo é mais forte. Cada resultado mostra sua pontuação, então você não precisa acreditar na palavra de ninguém.

Os mecanismos de busca públicos não vão bloquear ou degradar?

É projetado exatamente para isso: 18 mecanismos fundidos com fusão de rankings (qualquer um falhando mal move os resultados), uma escada de busca em camadas com aprendizado por domínio e um fallback opcional de agregador. Backends degradados são relatados na saída, e o cache local significa que tudo já visto continua funcionando independentemente.

Esse tipo de scraping é aceitável?

O wigolo lê a web pública como um navegador: robots.txt respeitado por padrão, limites de taxa por domínio e volumes de nível de pesquisa para um agente em uma máquina. Ele fica deliberadamente no extremo educado do espectro.

AGPL — posso usar isso no trabalho?

Sim, livremente, em toda a empresa. A licença só se aplica se você modificar o wigolo e executá-lo como um serviço de rede, caso em que deve publicar essas modificações; usá-lo como uma ferramenta de desenvolvimento local não gera nenhuma obrigação. Para dúvidas sobre licenciamento comercial, entre em contato.

Por que 1,5 GB de disco?

Esse é o cérebro no dispositivo: um mecanismo de navegador completo mais os modelos de ranqueamento e embeddings que os serviços em nuvem executam do lado deles e cobram de você. Uma vez no disco, cada consulta o usa gratuitamente.

Disponível em

• npm — wigolo (canal principal — o Quickstart acima)
• PyPI — wigolo (SDK Python)
• Docker — ghcr.io/knockoutez/wigolo · towhid69420/wigolo
• Registro oficial MCP — io.github.KnockOutEZ/wigolo
• Diretórios — Glama · Smithery · mcp.so · LobeHub

Homebrew, curl | sh e o binário de arquivo único são cobertos no guia de instalação. Use um canal por máquina; todos compartilham ~/.wigolo.

Contribuindo

Relatos de bugs, solicitações de recursos e PRs são todos bem-vindos; veja CONTRIBUTING.md. Mantenha os manipuladores de ferramentas enxutos, adicione testes e execute a suíte antes de abrir um PR. O ponto de entrada mais amigável é o sistema de plugins para mecanismos de busca e extratores personalizados: adicione um mecanismo de busca em ~100 linhas, com um modelo em examples/plugin-search-engine.

Licença

GNU AGPL-3.0-only. Livre para usar, modificar e auto-hospedar, inclusive dentro de uma empresa. A única obrigação: se você executar uma versão modificada como um serviço de rede, deve publicar seu código-fonte modificado sob a mesma licença. Isso mantém o wigolo aberto enquanto impede um fork hospedado fechado. Veja SECURITY.md para relatar uma vulnerabilidade e TRADEMARK.md para uso do nome. Para dúvidas sobre licenciamento comercial, entre em contato.