wigolo

---

wigolo le da a un agente de IA una única superficie para todo lo relacionado con la web: búsqueda, obtención, rastreo, extracción, caché, búsqueda de similares, investigación y bucles de recopilación autónomos. Se ejecuta dondequiera que se ejecute tu agente — como servidor MCP junto a tu agente de codificación, como endpoint REST/MCP en la máquina donde viven tus agentes autoalojados, o integrado mediante un SDK dentro de tu propia aplicación. Las herramientas principales no necesitan claves de API, nada de lo que tocan sale de ~/.wigolo/, y ninguna factura crece con lo mucho que tu agente piense.

Inicio 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

Requiere Node ≥ 20 y aproximadamente 1.5 GB de espacio libre en disco en macOS, Linux o Windows. init puro configura el motor local: descarga el motor del navegador y los modelos en el dispositivo, ejecuta una verificación de salud e informa de cada componente. Añadir --agents conecta los agentes nombrados en la misma ejecución, de modo que un agente de codificación que uses a diario queda listo con un solo comando.

• Agentes compatibles — --agents acepta cualquiera de claude-code · cursor · codex · gemini-cli · opencode · vscode · windsurf · zed · antigravity (separados por comas); wigolo escribe la configuración MCP y, donde se admite, las instrucciones para cada uno.
• Cualquier otra configuración — cualquier cliente MCP, framework de agentes o agente autoalojado registra npx -y wigolo en su propia configuración MCP. La guía de instalación tiene el bloque de configuración exacto para cada cliente, además de canales Docker, Homebrew y binario de archivo único.
• Más en camino — la lista compatible sigue creciendo, y se agradece un PR para añadir tu agente; consulta CONTRIBUTING.md.
• Configuración interactiva — --interactive es un flujo de texto plano; --wizard es la TUI de terminal completa.
• Diferir descargas — --no-warmup espera hasta el primer uso. Una descarga de componente fallida nunca hace fallar la configuración; init informa de lo que no está listo con la corrección exacta y aun así se completa.

init no requiere supervisión de forma predeterminada, por lo que es seguro en scripts y CI, y cualquier problema de configuración aparece aquí en el informe por componente, antes de la primera llamada de tu agente. Búsqueda, obtención, rastreo, extracción, caché y búsqueda de similares funcionan sin clave de API. Comprueba que está sano en cualquier momento:

npx wigolo doctor

Para eliminar todo limpiamente, ejecuta npx wigolo config --uninstall --yes. También puedes pegar la guía de instalación en cualquier asistente de IA y dejar que haga la configuración; está escrita para ser autocontenida.

Recomendado — una clave gratuita para research y agent

La búsqueda, obtención, rastreo, extracción, caché y búsqueda de similares son completamente sin claves. research, agent y search format=answer usan un LLM para redactar la respuesta sintetizada con citas. Sin uno, devuelven un informe breve y evidencia para que tu agente lo ensamble. Una clave gratuita de Gemini convierte eso en una respuesta terminada:

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

Cualquier proveedor funciona (anthropic · openai · groq), o mantente completamente local y sin claves con WIGOLO_LLM_PROVIDER=ollama (o cualquier URL compatible con OpenAI). Configúralo en tu shell o en el bloque env MCP de tu agente. Los proveedores, modelos y la escalera de modelos locales sin claves están en la guía de configuración.

Lo que tu agente recibe

Cada resultado de búsqueda es evidencia sobre la que el agente puede actuar. Lleva un extracto textual fijado a su posición exacta en la fuente, un ID de cita que el agente puede citar y una puntuación que puede inspeccionar (forma real abreviada):

{
  "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" }
}

Los resultados débiles se marcan como basura por el propio puntuador de wigolo. Los motores fallidos se informan y la caché obsoleta se etiqueta, de modo que el agente siempre sabe sobre qué se apoya. Los contratos de respuesta completos por herramienta están en la referencia de herramientas.

Herramientas

Herramienta	Qué hace
🔎 search	Búsqueda web multimotor (18 adaptadores directos) con fusión de rankings, reordenamiento con ML y una puntuación explicable por resultado. Pasa un array de consultas para amplitud en paralelo. Acota por dominio y rango de tiempo, coincide una frase exacta o devuelve resultados de imágenes.
📄 fetch	Carga una URL mediante un enrutador por niveles que escala automáticamente de HTTP plano a un motor de navegador sin interfaz ante desafíos antibot o shells SPA. Markdown limpio + metadatos + enlaces. Maneja PDFs, un section de un solo encabezado, sesiones autenticadas y acciones de página (clic / escribir / desplazarse / captura de pantalla).
🕸️ crawl	Rastreo multipágina — BFS, DFS, sitemap o solo mapa. Límites de velocidad por dominio, respeto a robots.txt, deduplicación de contenido repetido.
🧩 extract	Datos estructurados de una página: tablas, metadatos, JSON-LD, identidad de marca, esquemas nombrados (Artículo / Receta / Producto / …) o cualquier JSON Schema personalizado.
💾 cache	Consulta todo lo ya visto — por palabra clave o semántico híbrido. Además estadísticas, limpieza y detección de cambios.
🧲 find_similar	Páginas similares a una URL o un concepto, mediante fusión de 3 vías de palabra clave + semántico + web en vivo.
🧠 research	Descompone una pregunta → despliega subconsultas → obtiene fuentes → sintetiza un informe citado (o un informe breve estructurado que el LLM anfitrión redacta).
🤖 agent	Bucle de recopilación autónomo: planificar → buscar → obtener → extraer → sintetizar, con registro de pasos, presupuesto de tiempo y esquema de salida opcional.
🔁 diff + ⏱️ watch	Ve exactamente qué cambió en una página desde la última visita; vuelve a comprobar bajo demanda y entrega los cambios a un webhook.

Cada herramienta también se ejecuta desde la terminal (wigolo search "…" --json), desde un shell interactivo con canalización NDJSON (wigolo shell), mediante REST y a través de los SDK — referencia CLI. Las guías por herramienta con el conjunto completo de parámetros están en docs/tools.md; los ejemplos ejecutables están en examples/.

Por qué es diferente

wigolo no es un sustituto gratuito de las herramientas de pago — está construido para igualarlas. Es una capa web enfocada para tus agentes: una superficie MCP y REST a la que llaman directamente, con la calidad de búsqueda y extracción por la que los servicios de pago cobran. Lo que lo distingue:

• Construido para agentes. Una llamada MCP despliega muchas consultas en muchos motores en paralelo, algo que un bucle de herramientas host serial no puede replicar. Cada resultado lleva una puntuación transparente por resultado y la salida es consciente del presupuesto.
• Salida honesta. La caché obsoleta, las obtenciones fallidas, los backends degradados y la truncación se muestran en el resultado. Cuando una página protegida contra bots no se puede leer, obtienes un fallo blocked_by_challenge etiquetado, no un shell de desafío devuelto como contenido.
• $0 por consulta, libre de volver a consultar. La búsqueda predeterminada habla con motores públicos mediante adaptadores directos; el reordenador y las incrustaciones se ejecutan en el dispositivo. Cada respuesta se almacena en caché, así que volver a preguntar es instantáneo y no cuesta nada.
• Privado por defecto. La caché, las incrustaciones, los modelos y la configuración viven bajo ~/.wigolo/. Nada llega a un tercero a menos que optes explícitamente por un LLM para la síntesis.

Esto es lo que parece un resultado real, diseccionado. Incluye el motor fallido y el resultado débil, porque también son parte de la respuesta:

Patrocinadores

Gracias a los patrocinadores de abajo, que ayudan a mantener wigolo mantenido y gratuito para todos. Su apoyo va directamente al trabajo.

wigolo es gratuito para todos y tiene la intención de seguir siéndolo. Si tú o tu empresa queréis ayudar a mantenerlo, hay espacio para más patrocinadores — contacta en ktowhid20@gmail.com, o consulta SPONSORS.md para los términos. También se agradece una donación puntual mediante Buy Me a Coffee.

Benchmark

Las cuatro herramientas convergieron en la misma respuesta central, y solo una de ellas devolvió evidencia textual fijada a bytes mientras lo hacía.

Una consulta en frío se ejecutó en vivo dentro de una única sesión de Claude Fable 5, se desplegó a cuatro herramientas web en igualdad de condiciones (WebSearch integrado, wigolo, Tavily, Exa), y el agente la juzgó solo por la evidencia. Las cuatro convergieron en la misma respuesta y la misma fuente principal, así que la paridad queda demostrada en pantalla. Solo wigolo devolvió extractos textuales fijados a intervalos de origen con desplazamiento de bytes, una descomposición de puntuación explicable y telemetría en vivo por motor, y su propio puntuador marcó dos resultados débiles como basura. Las herramientas en la nube también merecen su lugar: Exa renderizó la matriz de comparación de los documentos oficiales completa. Ejecuta tu propia consulta y verás la misma forma.

Cómo se compara

	wigolo	Firecrawl	Exa	Tavily
Búsqueda web multimotor	✅	✅	✅	✅
Obtención y extracción estructurada	✅	✅	✅	✅
Rastreo y mapa de sitio completo	✅	✅	—	✅
Extractos textuales fijados a intervalos de origen con desplazamiento de bytes	✅	—	—	—
Descomposición de puntuación explicable por resultado	✅	—	—	—
Memoria local persistente — re-consulta instantánea, sin conexión	✅	—	—	—
Los datos de consulta permanecen en tu máquina	✅	—	—	—
Clave de API / cuenta	ninguna	requerida	requerida	requerida
Coste por consulta	$0	medido	medido	medido

_{Estado de funciones a julio de 2026 — consulta la documentación de cada proveedor para el estado actual.}

Esa última fila se acumula, porque los agentes preguntan en ráfagas:

Más allá de tu editor

Las mismas diez herramientas sirven a todo tipo de agente, sobre cualquier superficie que encaje: MCP para agentes de codificación, REST para todo lo demás, SDK para integrar y wrappers de frameworks para insertar.

API REST — wigolo serve

Un proceso expone una API REST JSON plano junto al transporte MCP. No se necesita cliente MCP, solo 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} cubre las diez herramientas, GET /openapi.json es el contrato OpenAPI 3.1, y /mcp + /sse atienden a clientes MCP remotos desde el mismo puerto. Si se vincula más allá de loopback, se requiere un token bearer, por lo que el servidor falla de forma segura por defecto. Apunta n8n, un asistente estilo Hermes, o cualquier agente autoalojado hacia él. → API REST

SDKs — TypeScript y Python

Clientes ligeros y tipados con un modo local integrado que encuentra o inicia el daemon por ti. Sin paso separado de serve.

TypeScript — npm install wigolo-sdk (sin dependencias; 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 (solo biblioteca estándar; síncrono + así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 y modo integrado

Integraciones con frameworks

Integra las herramientas de wigolo en el framework que ya usas. Obtienes la superficie completa de diez herramientas, incluyendo cache / find_similar / research / agent que la mayoría de las herramientas web de frameworks no incluyen:

Framework	Paquete	Lo que obtienes
LangChain	wigolo-langchain	cada herramienta como un BaseTool, más un BaseRetriever sobre search / find_similar para RAG
CrewAI	wigolo-crewai	wigolo_tools() → pasa el conjunto a cualquier crew
LlamaIndex	wigolo-llamaindex	un BaseReader que carga páginas obtenidas / rastreadas / buscadas como documentos
Vercel AI SDK	wigolo-vercel-ai-sdk	fábricas de herramientas para generateText / streamText, compatible con edge

→ Integraciones con 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

La imagen ligera carga modelos de forma diferida en el volumen; :full preinstala el motor del navegador. También en Docker Hub como towhid69420/wigolo. → instalación y todos los canales

Habilidades para agentes

Un catálogo de 11 habilidades enseña a tu agente de codificación a manejar bien cada herramienta. Se instala con init y se gestiona con wigolo skills add|list|remove. → habilidades

Una nota para quienes se autoalojan: algunos sitios protegidos contra desafíos evalúan la reputación de la IP, por lo que una IP de centro de datos no superará barreras que una conexión doméstica sí. wigolo etiqueta esos fallos, y la guía de autoalojamiento cubre la respuesta opcional con proxy.

Historial de estrellas

Arquitectura

Un único proceso Node habla MCP (JSON-RPC sobre stdio). Todo lo pesado es local y se carga de forma diferida, por lo que una instalación sin claves no paga nada por las partes que no usa.

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

• El código supera al modelo. El trabajo determinista se mantiene fuera del LLM: canonicalización, fusión de rankings, deduplicación y coincidencia de esquemas. El modelo se reserva para juicio, es opcional y está limitado por solicitud. Los campos rellenados por el LLM se verifican contra la fuente y se anulan si están ausentes.
• Enrutamiento basado en señales. La escalera de obtención asciende a un navegador real según señales observables, no suposiciones de dominio: marcadores SPA, cuerpos de desafío, contenido escaso. Aprende por dominio, desaprende cuando un sitio deja de necesitarlo, y wigolo tune list te muestra exactamente lo que aprendió.
• Lee las páginas como lo haría un navegador. La obtención por niveles espera a los desafíos intersticiales y reutiliza los permisos por dominio, de forma educada: robots.txt respetado, límites de tasa por dominio, volúmenes de grado de investigación. Cuando una barrera persiste, el fallo se etiqueta y se informa.

Configuración

Una instalación limpia funciona de inmediato. Tres ajustes mejoran la calidad de salida:

# 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 llamada que valen la pena: consultas en arrays (["a","b","c"]) para amplitud en paralelo · search_depth: "deep" para consultas importantes · include_domains como filtro estricto para búsquedas de documentación. La referencia completa cubre cada variable de entorno, clave de archivo de configuración, backend de búsqueda, TTL de caché y límite de servicio; está en la guía de configuración.

Documentación y ejemplos

docs/ — el manual completo: primeros pasos · instalación y canales · configuración · referencia de herramientas · CLI y shell · API REST · SDKs e integraciones · autoalojamiento · habilidades para agentes · plugins · solución de problemas y preguntas frecuentes · privacidad y seguridad

examples/ — ejecutables, cada uno con un README (y la mayoría con una grabación de terminal): CLI de un solo uso, pipelines de shell NDJSON, REST mediante curl, SDKs de TypeScript y Python, herramientas de Vercel AI SDK, apuntar n8n autoalojado a un wigolo remoto, watch con webhook, y escribir tu propio plugin de motor de búsqueda. La documentación también se muestra en el sitio en knockoutez.github.io/wigolo/docs.

Beta y comentarios

wigolo está en beta pública. Todo lo documentado aquí funciona y se mantiene con una suite de 7,600 pruebas; es estable, y la beta trata sobre el estándar de pulido. Sigue en beta hasta que suficientes personas lo hayan usado, pateado y marcado con estrella para que llamarlo v1 signifique algo. Tus comentarios dan forma a lo que viene después, y cada informe se lee, normalmente el mismo día:

• 🐛 Informar de un error — se rompió, se comportó mal, te sorprendió
• 💡 Solicitar una función — algo que debería hacer
• 💬 Preguntar cualquier cosa — preguntas, configuraciones, mostrar y contar

Si wigolo se gana un lugar en tu configuración, tres cosas lo mantienen en marcha: una ⭐ estrella (así se encuentra el código abierto), un ☕ café (no hay nivel de pago y nunca lo habrá), o un correo electrónico que va directo al único desarrollador que escribió el código.

Solución de problemas

wigolo doctor nombra cualquier componente roto y la variable de entorno o comando exacto que lo arregla; wigolo doctor --fix repara los casos comunes, y wigolo verify verifica el estado de cada componente. Un componente que falla durante init no rompe wigolo: init sigue saliendo con 0, y la búsqueda / obtención / rastreo / extracción / caché principales funcionan sin modelos y sin navegador. Consejos rápidos:

• Descargas lentas o fallidas — vuelve a ejecutar wigolo warmup --all (o --browser / --embeddings / --reranker); se reanudan y reintentan.
• El navegador no se inicia en Linux — wigolo warmup --browser instala las bibliotecas del sistema operativo (o imprime el comando exacto).
• Error de compilación nativa / Node inusual — usa un LTS: Node 20, 22 o 24.
• Detrás de un proxy — USE_PROXY=true + PROXY_URL; añade NODE_EXTRA_CA_CERTS para proxies que inspeccionan TLS.

La guía completa cubre soluciones por síntoma, un mapa de "qué sigue funcionando cuando X falla", notas de plataforma (incl. linux-arm64) e instalaciones sin conexión: docs/troubleshooting.md.

Preguntas frecuentes

¿Gratis? ¿Cuál es el truco?

Sin truco por diseño. Las partes caras (ranking, embeddings, el motor del navegador) se ejecutan en tu hardware, por lo que no hay costo por consulta que recuperar ni razón para un medidor. Se sostiene con donaciones, y la licencia AGPL impide legalmente un cambio a un producto alojado cerrado.

¿La calidad está realmente a la par de los servicios de pago?

La sección de benchmarks anterior es una ejecución en vivo de 4 vías que puedes reproducir: las consultas cotidianas de agentes llegan a la paridad, las herramientas de pago aún ganan algunos casos límite de extracción profunda, y el rastreo es donde wigolo es más fuerte. Cada resultado muestra su puntuación, así que no tienes que creer a nadie bajo palabra.

¿No bloquearán o degradarán los motores de búsqueda públicos?

Está diseñado exactamente para eso: 18 motores fusionados con fusión de rankings (cualquier fallo apenas mueve los resultados), una escalera de obtención por niveles con aprendizaje por dominio, y un respaldo opcional de agregador. Los backends degradados se informan en la salida, y la caché local significa que todo lo ya visto sigue funcionando independientemente.

¿Este tipo de scraping está bien?

wigolo lee la web pública como lo haría un navegador: robots.txt respetado por defecto, límites de tasa por dominio y volúmenes de grado de investigación para un agente en una máquina. Se sitúa deliberadamente en el extremo educado del espectro.

AGPL — ¿puedo usarlo en el trabajo?

Sí, libremente, en toda la empresa. La licencia solo aplica si modificas wigolo y lo ejecutas como un servicio de red, en cuyo caso debes publicar esas modificaciones; usarlo como herramienta de desarrollo local no conlleva ninguna obligación. Para preguntas sobre licencias comerciales, contacta.

¿Por qué 1.5 GB de disco?

Ese es el cerebro en el dispositivo: un motor de navegador completo más los modelos de ranking y embeddings que los servicios en la nube ejecutan en su lado y te cobran. Una vez en disco, cada consulta lo usa gratis.

Disponible en

• npm — wigolo (canal principal — el Quickstart anterior)
• PyPI — wigolo (SDK de Python)
• Docker — ghcr.io/knockoutez/wigolo · towhid69420/wigolo
• Registro oficial de MCP — io.github.KnockOutEZ/wigolo
• Directorios — Glama · Smithery · mcp.so · LobeHub

Homebrew, curl | sh y el binario de archivo único se cubren en la guía de instalación. Usa un canal por máquina; todos comparten ~/.wigolo.

Contribuciones

Los informes de errores, solicitudes de funciones y PRs son bienvenidos; consulta CONTRIBUTING.md. Mantén los manejadores de herramientas ligeros, añade pruebas y ejecuta la suite antes de abrir un PR. El punto de entrada más amigable es el sistema de plugins para motores de búsqueda y extractores personalizados: añade un motor de búsqueda en ~100 líneas, con una plantilla en examples/plugin-search-engine.

Licencia

GNU AGPL-3.0-only. Libre de usar, modificar y autoalojar, incluso dentro de una empresa. La única obligación: si ejecutas una versión modificada como servicio de red, debes publicar tu fuente modificada bajo la misma licencia. Eso mantiene wigolo abierto mientras impide un fork alojado cerrado. Consulta SECURITY.md para informar de una vulnerabilidad y TRADEMARK.md para el uso del nombre. Para preguntas sobre licencias comerciales, contacta.