---

wigolo 为 AI Agent 提供处理一切 Web 相关任务的统一平台——搜索、抓取、爬取、提取、缓存、相似检索、研究以及自主采集循环。它能在 Agent 运行的任何地方工作：作为 MCP 服务器紧邻你的编码 Agent，作为 REST/MCP 端点运行在自托管 Agent 所在主机上，或通过 SDK 嵌入你自己的应用。核心工具无需 API 密钥，所有接触的内容都留在 ~/.wigolo/ 内，且不会产生随 Agent 思考量增长的费用。

需要 Node ≥ 20 及约 1.5 GB 可用磁盘空间。支持 macOS、Linux 和 Windows。

一条命令将本地引擎接入你的 Agent。init 默认无交互——没有提示，可安全用于脚本和 CI——并完成完整设置：下载浏览器引擎和本地模型，执行健康检查，输出各组件摘要，使得任何设置问题都会在此暴露，而不会在 Agent 首次调用时悄然失败：

npx wigolo init --agents=

• <your-agent>——以下一个或多个，逗号分隔：claude-code · cursor · codex · gemini-cli · vscode · windsurf · zed · antigravity。wigolo 会为你写入 MCP 配置和说明。
• **任何其他 MCP 客户端？**省略 --agents 并自行注册 npx -y wigolo——安装指南 为每个客户端提供了精确的配置块，并提供了 Docker、Homebrew 和单文件二进制安装通道。
• 偏好交互提示？--interactive 为纯文本流程；--wizard 为完整终端 TUI。
• 跳过下载？--no-warmup 将所有内容推迟到首次使用。组件下载失败不会导致设置失败——init 会报告未就绪项并给出准确修复方法，同时仍能完成 Agent 的接入。

这就是全部设置——**搜索、抓取、爬取、提取、缓存和相似检索无需任何 API 密钥即可工作。**随时检查是否健康：

不适合你？npx wigolo config --uninstall --yes 会干净地移除一切。你也可以将安装指南粘贴给任何 AI 助手并让它完成设置——指南本身是自包含的。

推荐——免费密钥让 research 和 agent 表现更佳

搜索、抓取、爬取、提取、缓存和相似检索完全无需密钥。但 research、agent 和 search format=answer 会使用 LLM 撰写 合成并带引用的答案——若没有 LLM，它们只返回原始摘要和证据，供你的 Agent 自行组装，体验会大打折扣。只需一个免费 Gemini 密钥，这是你能做的最大质量提升：

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

任何提供商都可使用（anthropic · openai · groq），也可通过 WIGOLO_LLM_PROVIDER=ollama（或任何 OpenAI 兼容 URL）保持完全本地且无密钥。在你的 shell 或 Agent 的 MCP env 块中设置即可。提供商、模型和无密钥本地模型阶梯，请参阅配置指南。

你的 Agent 得到的不是片段，而是证据

每个搜索结果都带有与来源中准确位置对应的逐字摘录、Agent 可引用的引用 ID，以及可检查的评分（精简后的真实形态）：

弱结果会被 wigolo 自己的评分器标记为垃圾，失败的引擎会被报告，过期的缓存会被标注——Agent 始终清楚其依据。各工具的完整响应契约请参阅工具参考。

工具	功能
🔎 search	多引擎网络搜索（18 个直接适配器），采用排名融合、ML 重排序，并为每个结果提供可解释的评分。传递查询数组实现并行广度搜索。
📄 fetch	通过分层路由加载一个 URL，在遇到反爬挑战或 SPA 外壳时，自动从纯 HTTP 升级到无头浏览器引擎。返回干净的 Markdown + 元数据 + 链接。
🕸️ crawl	多页爬取——BFS、DFS、站点地图或仅地图。遵守每域速率限制、robots.txt，并进行样板去重。
🧩 extract	从页面提取结构化数据：表格、元数据、JSON-LD、品牌标识、具名模式（Article / Recipe / Product / …），或任何自定义 JSON Schema。
💾 cache	查询所有已见内容——关键词或混合语义。以及统计、清除和变更检测。
🧲 find_similar	寻找与某个 URL 或概念相似的页面，通过关键词 + 语义 + 实时网络的三路融合实现。
🧠 research	分解问题 → 扇出子查询 → 获取来源 → 合成带引用的报告（或由宿主 LLM 根据结构化摘要撰写）。
🤖 agent	自主采集循环：计划 → 搜索 → 抓取 → 提取 → 合成，包含步骤日志、时间预算和可选输出模式。
🔁 diff + ⏱️ watch	查看页面自上次访问以来的确切变化；按需重新检查并将变更发送到 Webhook。

每个工具也可从终端运行（wigolo search "…" --json），从支持 NDJSON 管道的交互式 Shell（wigolo shell）运行，通过 REST 以及 SDK 调用——CLI 参考。

这实际能让你做什么

每个工具的能力远不止一行概述。以下是一组示例——每行都链接到指南，并在有实例时提供可运行示例：

• 分支搜索——传递查询数组实现并行广度，通过 include_domains 限定范围，用 time_range/recency 约束时间，精确短语匹配，选择深度层级，甚至获取图片结果。→ 指南 · 示例
• 抓取几乎一切——JS 渲染的 SPA、PDF、单个标题 section、需认证页面（通过浏览器配置文件或远程浏览器），或通过 actions 操控页面（点击/输入/滚动/截图）。→ 指南
• 爬取整个网站——站点地图、BFS、DFS 或仅地图；遵守 robots.txt，按域限速，样板去重。→ 指南
• 提取结构——表格、JSON-LD、元数据、品牌资源、具名模式（Article / Recipe / Product / …），或你自己的 JSON Schema。→ 指南
• 累积型记忆——每个页面都被缓存；通过关键词或语义即时离线重新查询；检测自上次访问以来的变化。→ 指南 · 示例
• 研究 & 自主采集——将问题分解为带引用的摘要，或让 agent 自由计划 → 抓取 → 提取 → 合成，遵循 JSON Schema 和时间预算。→ 指南 · 示例
• 监控 & 差异——监控一个 URL，获取变更报告，发送到 Webhook。→ 指南 · 示例
• 按你的方式驱动——一次性 CLI、用于管道的 NDJSON Shell、REST、SDK，或作为 Agent 安装的技能。→ CLI 与 Shell · 示例
• 扩展它——用约 100 行代码添加搜索引擎或站点提取器作为插件。→ 插件 · 示例
• 调优与检查——wigolo tune 显示每个域的学习情况（采用哪一层抓取、挑战清除、退避策略）；doctor / verify 对每个组件进行健康检查。→ CLI · 故障排除

wigolo 不是你在预算到位前将就使用的免费替代品——它的目标是与此赛道的付费服务保持同一水准，并且提供证据。它真正与众不同之处：

• **为 Agent 设计，而非人类。**一次 MCP 调用即可并行向多个引擎发起大量查询——这是串行主机工具循环无法复制的——并提供透明的逐结果评分和预算感知输出。
• **诚实的输出。**过时缓存、抓取失败、后端降级和截断信息会直接反映在结果中，从不伪装成空但成功的数据。当受保护页面无法读取时，你会得到标记为 blocked_by_challenge 的失败信息——绝不会将挑战外壳伪装成内容。
• **每次查询零成本，自由重复查询。**默认搜索通过直接适配器访问公共引擎；重排序和嵌入在本地运行。每个响应都被缓存，因此再次请求即刻完成且零开销。
• **默认隐私。**缓存、嵌入、模型和配置都存储在 ~/.wigolo/ 下。除非你显式选择使用 LLM 进行合成，否则不会触达任何第三方。

wigolo 是为 Agent 打造的专注 Web 层——不是托管的 SaaS、其他应用查询的向量数据库或规模化抓取平台。在此赛道内，它在结果质量上与付费服务不相上下——而计量表、密钥和数据流出压根不存在。

以下是剖析的真实结果样本——包括失败的引擎和弱结果，因为这些同样是答案的一部分：

所有四个工具汇聚到同一核心答案——而其中只有一个在做到的同时返回了逐字、字节定位的证据。

一次冷查询，在同一个 Claude Fable 5 会话中实时运行，并平等地扇出到四个 Web 工具——内置 WebSearch、wigolo、Tavily 和 Exa——然后由 Agent 本身按一条规则报告：仅凭证据评判，不偏袒。所有四个工具汇聚到相同答案和相同首选来源——展示的是对等性，而非声称。wigolo 单独返回了定位到字节偏移源区间的逐字摘录、可解释的评分子项以及每种引擎的实时遥测——当其中两个结果较弱时，其评分器会在界面上将其标记为垃圾。云端工具也有其价值：Exa 完整渲染了官方文档的比较矩阵。这是一次诚实的查询，而非排行榜——你自己运行就会看到相同的结果形态。

同一场较量，不同的物理

wigolo	Firecrawl	Exa	Tavily
多引擎网络搜索	✅	✅	✅
抓取与结构化提取	✅	✅	✅
全站爬取与站点地图	✅	✅	—
定位到字节偏移源区间的逐字摘录	✅	—	—
可解释的逐结果评分子项	✅	—	—
持久本地记忆——即时离线重新查询	✅	—	—
查询数据留在你的机器上	✅	—	—
API 密钥 / 账户	无需	必须	必须
每次查询成本	$0	按量计费	按量计费

截至 2026 年 7 月的功能现状——请查阅各供应商文档了解最新状态。

最后一行的影响是复合的——Agent 不会只查询一次，而是成簇地查询：

同样的十个工具服务于每种 Agent，通过任何合适的形式——MCP 用于编码 Agent，REST 用于其他一切，SDK 用于嵌入，框架封装器用于开箱即用。

一个进程在 MCP 传输端口旁额外暴露一个纯 JSON REST API。无需 MCP 客户端——只需 curl：

wigolo serve # 127.0.0.1:3333 — 环回地址开放；外部访问需令牌

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} 覆盖全部十个工具，GET /openapi.json 是 OpenAPI 3.1 契约，/mcp 和 /sse 在同一端口为远程 MCP 客户端服务。绑定到环回之外的地址时需要持有令牌——服务器默认拒绝外部访问，而非无意中敞开。可将 n8n、Hermes 式助手或任何自托管 Agent 指向该服务。→ REST API

SDK——TypeScript 与 Python

轻量、类型化的客户端，内置本地模式可自动查找或启动守护进程——无需单独的 serve 步骤。

TypeScript — npm install wigolo-sdk（零依赖；支持 Node / Bun / Deno / edge）：

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

const { client, close } = await createLocalClient(); // 复用已有守护进程，或启动一个 const res = await client.search({ query: 'local-first web search', max_results: 5 }); console.log(res.results.map((r) => r.title)); await close(); // 仅在本次调用启动了守护进程时才停止它

Python — pip install wigolo（仅标准库；同步 + 异步）：

from wigolo import local_client

with local_client() as client: # 复用健康的守护进程，或启动一个 res = client.search(query="local-first web search", max_results=5) for r in res["results"]: print(r["title"], r["url"])

→ SDK 与嵌入模式

将 wigolo 的工具引入你已在使用的框架——完整的十个工具面，包括缓存 / 相似检索 / 研究 / 自主采集等大多数框架 Web 工具不提供的功能：

框架	包	功能
LangChain	wigolo-langchain	每个工具作为一个 BaseTool，以及涵盖搜索 / 相似检索的 BaseRetriever 用于 RAG
CrewAI	wigolo-crewai	wigolo_tools() → 将集合交给任意 crew
LlamaIndex	wigolo-llamaindex	一个 BaseReader，将已抓取 / 爬取 / 搜索的页面作为文档加载
Vercel AI SDK	wigolo-vercel-ai-sdk	用于 generateText / streamText 的工具工厂，对边缘环境友好

→ 框架集成

stdio MCP — wire it into any MCP client as command: docker

docker run

---

wigolo gives an AI agent one durable surface for everything web-related — search, fetch, crawl, extract, cache, find-similar, research, and autonomous gather loops. It runs wherever your agent runs: as an MCP server next to your coding agent, as a REST/MCP endpoint on the box where your self-hosted agents live, or embedded through an SDK inside your own app. The core tools need no API keys, nothing it touches leaves ~/.wigolo/, and there's no bill that grows with how much your agent thinks.

Requires Node ≥ 20 and ~1.5 GB of free disk. macOS, Linux, and Windows.

One command wires the local engine into your agent. init is unattended by default — no prompts, safe in scripts and CI — and does the complete setup : it downloads the browser engine and on-device models, runs a health check, and prints a per-component summary, so any setup problem surfaces right here, not silently on your agent's first call:

npx wigolo init --agents=<your-agent>

• <your-agent> — one or more of claude-code · cursor · codex · gemini-cli · vscode · windsurf · zed · antigravity (comma-separated). wigolo writes the MCP config and instructions for you.
• Any other MCP client? Omit --agents and register npx -y wigolo yourself — the installation guide has the exact config block for every client, plus Docker, Homebrew, and single-file-binary channels.
• Prefer prompts? --interactive is a plain-text flow; --wizard is the full terminal TUI.
• Skip the downloads? --no-warmup defers everything to first use. A failed component download never fails setup — init reports what's not ready with the exact fix and still wires your agent.

That's the whole setup — search, fetch, crawl, extract, cache, and find-similar work with no API key. Check it's healthy anytime:

Not for you? npx wigolo config --uninstall --yes removes everything, cleanly. You can also paste the installation guide at any AI assistant and let it do the setup — it's written to be self-contained.

Recommended — a free key makes research & agent shine

Search, fetch, crawl, extract, cache, and find-similar are fully keyless. But research, agent, and search format=answer use an LLM to write the synthesized, cited answer — without one they hand back a raw brief and evidence for your agent to assemble, which is a much thinner experience. A free Gemini key is all it takes , and it's the single biggest quality upgrade you can make:

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

Any provider works (anthropic · openai · groq), or stay fully local and keyless with WIGOLO_LLM_PROVIDER=ollama (or any OpenAI-compatible URL). Set it in your shell or your agent's MCP env block. Providers, models, and the keyless local-model ladder: configuration guide.

What your agent gets back

Not snippets — evidence. Every search result carries a verbatim excerpt pinned to its exact position in the source, a citation ID the agent can quote, and a score it can inspect (abridged real shape):

Weak results get flagged as junk by wigolo's own scorer, failed engines are reported, stale cache is labeled — the agent always knows what it's standing on. Full response contracts per tool: tools reference.

Tool	What it does
🔎 search	Multi-engine web search (18 direct adapters) with rank fusion, ML reranking, and an explainable per-result score. Pass a query array for parallel breadth.
📄 fetch	Load one URL through a tiered router that auto-escalates from plain HTTP to a headless browser engine on anti-bot challenges or SPA shells. Clean markdown + metadata + links.
🕸️ crawl	Multi-page crawl — BFS, DFS, sitemap, or map-only. Per-domain rate limits, robots.txt respect, boilerplate dedup.
🧩 extract	Structured data from a page: tables, metadata, JSON-LD, brand identity, named schemas (Article / Recipe / Product / …), or any custom JSON Schema.
💾 cache	Query everything already seen — keyword or hybrid semantic. Plus stats, clear, and change detection.
🧲 find_similar	Pages similar to a URL or a concept, via 3-way fusion of keyword + semantic + live web.
🧠 research	Decompose a question → fan out sub-queries → fetch sources → synthesize a cited report (or a structured brief the host LLM writes from).
🤖 agent	Autonomous gather loop: plan → search → fetch → extract → synthesize, with a step log, time budget, and optional output schema.
🔁 diff + ⏱️ watch	See exactly what changed on a page since last visit; re-check on demand and deliver changes to a webhook.

Every tool also runs from the terminal (wigolo search "…" --json), from an interactive shell with NDJSON piping (wigolo shell), over REST, and through the SDKs — CLI reference.

What that actually lets you do

Each tool goes well past its one-liner. A sampler — every line links to the guide and, where there's one, a runnable example:

• Search that fans out — pass a query array for parallel breadth, scope to include_domains, bound by time_range/recency, exact-phrase match, choose a depth tier, even image results. → guide · example
• Fetch almost anything — JS-rendered SPAs, PDFs, a single heading section, authenticated pages (via a browser profile or remote browser), or drive the page with actions (click / type / scroll / screenshot). → guide
• Crawl a whole site — sitemap, BFS, DFS, or map-only; robots.txt-respecting, per-domain rate-limited, boilerplate-deduped. → guide
• Extract structure — tables, JSON-LD, metadata, brand assets, named schemas (Article / Recipe / Product / …), or your own JSON Schema. → guide
• A memory that compounds — every page is cached; re-query by keyword or meaning, instantly and offline; detect what changed since last visit. → guide · example
• Research & autonomous gather — decompose a question into a cited brief, or turn agent loose to plan → fetch → extract → synthesize against a JSON Schema and a time budget. → guide · example
• Watch & diff — monitor a URL, get a change report, deliver it to a webhook. → guide · example
• Drive it your way — one-shot CLI, an NDJSON shell for pipelines, REST, SDKs, or as skills your agent installs. → CLI & shell · example
• Extend it — add a search engine or a site extractor as a plugin in ~100 lines. → plugins · example
• Tune & inspect — wigolo tune shows what it learned per domain (which fetch tier, challenge clearances, backoff); doctor / verify health-check every component. → CLI · troubleshooting

wigolo isn't the free stand-in you settle for until the budget clears — it's built to hold the same line as the paid services in this lane, and it brings receipts. What actually separates it:

• Built for agents, not humans. One MCP call fans out many queries across many engines in parallel — something a serial host tool-loop can't replicate — with transparent per-result scoring and budget-aware output.
• Honest output. Stale cache, failed fetches, degraded backends, and truncation are surfaced in the result, never disguised as empty-but-successful data. When a bot-protected page can't be read, you get a labeled blocked_by_challenge failure — never a challenge shell dressed up as content.
• $0 per query, free to re-query. Default search talks to public engines through direct adapters; the reranker and embeddings run on-device. Every response is cached, so asking again is instant and costs nothing.
• Private by default. Cache, embeddings, models, and config live under ~/.wigolo/. Nothing reaches a third party unless you explicitly opt into an LLM for synthesis.

wigolo is a focused web layer for your agents — not a hosted SaaS, a vector database other apps query, or a scale-scraping platform. Within that lane it goes toe-to-toe with the paid services on result quality — and the meter, the key, and the data-egress simply aren't there.

Here's what one real result looks like, dissected — including the failed engine and the weak result, because those are part of the answer too:

All four tools converged on the same core answer — and only one of them handed back verbatim, byte-pinned evidence while doing it.

One cold query, run live inside a single Claude Fable 5 session and fanned out to four web tools on equal footing — built-in WebSearch , wigolo , Tavily , and Exa — then reported by the agent itself under one rule: judge on the evidence alone, no favoritism. All four converged on the same answer and the same top source — parity demonstrated, not asserted. wigolo alone returned verbatim excerpts pinned to byte-offset source spans, an explainable score decomposition, and live per-engine telemetry — and when two of its results were weak, its own scorer flagged them as junk on-screen. The cloud tools earn their line too: Exa rendered the official docs' comparison matrix in full. One honest query, not a leaderboard — run your own and you'll see the same shape.

Same fight, different physics

| wigolo | Firecrawl | Exa | Tavily
---|---|---|---|---
Multi-engine web search | ✅ | ✅ | ✅ | ✅
Fetch & structured extraction | ✅ | ✅ | ✅ | ✅
Whole-site crawl & map | ✅ | ✅ | — | ✅
Verbatim excerpts pinned to byte-offset source spans | ✅ | — | — | —
Explainable per-result score decomposition | ✅ | — | — | —
Persistent local memory — re-query instantly, offline | ✅ | — | — | —
Query data stays on your machine | ✅ | — | — | —
API key / account | none | required | required | required
Cost per query | $0 | metered | metered | metered

Feature standing as of July 2026 — check each vendor's docs for current state.

That last row is the one that compounds — agents don't ask once, they ask in bursts:

The same ten tools serve every kind of agent, over whichever surface fits — MCP for coding agents, REST for everything else, SDKs to embed, framework wrappers to drop in.

One process exposes a plain-JSON REST API next to the MCP transport. No MCP client needed — just 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} covers all ten tools, GET /openapi.json is the OpenAPI 3.1 contract, and /mcp + /sse serve remote MCP clients from the same port. Bind past loopback and a bearer token is required — the server fails closed rather than opening wide by accident. Point n8n, a Hermes-style assistant, or any self-hosted agent at it. → REST API

SDKs — TypeScript & Python

Thin, typed clients with an embedded local mode that finds or starts the daemon for you — no separate serve step.

TypeScript — npm install wigolo-sdk (zero-dep; 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 (standard library only; sync + async):

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 & embedded mode

Drop wigolo's tools into the framework you already use — the full ten-tool surface, including the cache / find_similar / research / agent that most framework web-tools don't ship:

Framework	Package	What you get
LangChain	wigolo-langchain	each tool as a BaseTool, plus a BaseRetriever over search / find_similar for RAG
CrewAI	wigolo-crewai	wigolo_tools() → hand the set to any crew
LlamaIndex	wigolo-llamaindex	a BaseReader that loads fetched / crawled / searched pages as documents
Vercel AI SDK	wigolo-vercel-ai-sdk	tool factories for generateText / streamText, edge-friendly

→ Framework integrations

# 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

The slim image lazy-loads models into the volume; :full preinstalls the browser engine. Also on Docker Hub as towhid69420/wigolo. → installation & all channels

An 11-pack skill catalog teaches your coding agent to drive each tool well — installed by init, managed with wigolo skills add|list|remove. → skills

One honest note for self-hosters: some challenge-protected sites score IP reputation, so a datacenter IP won't clear walls a home connection would. wigolo labels those failures instead of faking them, and the self-hosting guide covers the opt-in proxy answer.

Live chart — it updates itself. If it's still climbing when you read this, add a ⭐.

A single Node process speaking MCP (JSON-RPC over stdio). Everything heavy is local and lazy-loaded, so a zero-key install pays nothing for the parts it isn't using.

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

Loading

• Code beats model. Deterministic work — canonicalization, rank fusion, dedup, schema matching — never touches an LLM. The model is reserved for judgment, opt-in, and capped per request; LLM-filled fields are checked against the source and nulled if absent.
• Routing on observable signals. The fetch ladder escalates to a real browser on what it sees — SPA markers, challenge bodies, thin content — not domain guesses. It learns per domain, unlearns when a site stops needing it, and wigolo tune list shows you exactly what it learned.
• Reads pages the way a browser does — and says so when it can't. Tiered fetching waits out interstitial challenges and reuses clearances per domain, politely: robots.txt respected, per-domain rate limits, research-grade volumes. When a wall stays up, the failure is labeled, never disguised.

A clean install works out of the box. Three settings meaningfully raise output quality:

# 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

Per-call habits that pay off: query arrays (["a","b","c"]) for parallel breadth · search_depth: "deep" for queries that matter · include_domains as a hard filter for docs lookups.

The full reference — every environment variable, config-file key, search backend, cache TTL, and serve limit — lives in the configuration guide.

docs/ — the complete manual: getting started · installation & channels · configuration · tools reference · CLI & shell · REST API · SDKs & integrations · self-hosting · agent skills · plugins · troubleshooting & FAQ · privacy & security

examples/ — runnable, each with a README (and most with a terminal recording): one-shot CLI, NDJSON shell pipelines, REST via curl, TypeScript & Python SDKs, Vercel AI SDK tools, pointing self-hosted n8n at a remote wigolo, watch-with-webhook, and writing your own search-engine plugin.

Docs are also rendered on the site: knockoutez.github.io/wigolo/docs.

wigolo is in public beta. Everything documented here works and is held to a 7,600-test suite — beta is about the polish bar, not stability. It stays beta until enough people have used it, kicked it, and starred it that calling it v1 means something.

That makes your feedback the whole game right now. Every report is read, usually the same day:

And if wigolo earns a place in your setup, the ways to keep it alive: a ⭐ star (it's how open source gets found), a ☕ coffee (there's no paid tier and never will be), or just an email — it goes straight to the one developer who wrote the code.

Free? What's the catch?

No catch by design. The expensive parts — ranking, embeddings, the browser engine — run on your hardware, so there's no per-query cost to recover and no reason for a meter. Sustained by donations; the AGPL license legally prevents a bait-and-switch into a closed hosted product.

Is the quality really on par with the paid services?

Run one query and judge — the benchmark section above is a live 4-way run, not a chart. Everyday agent queries land at parity; the paid tools still win some deep-extraction edge cases, and crawling is where wigolo is strongest. Every result shows its scoring, so you don't have to take anyone's word for it.

Won't public search engines block or rot?

It's engineered for exactly that: 18 engines fused with rank fusion (any one failing barely moves results), a tiered fetch ladder with per-domain learning, and an optional aggregator fallback. Degraded backends are reported in the output , never hidden — and the local cache means everything already seen keeps working regardless.

Is this kind of scraping OK?

wigolo reads the public web the way a browser does — robots.txt respected by default, per-domain rate limits, research-grade volumes for one agent on one machine. It's deliberately the polite end of the spectrum, not a harvesting platform.

AGPL — can I use this at work?

Yes, freely, company-wide. The license only bites if you modify wigolo and run it as a network service — then you must publish those modifications. Using it as a local dev tool carries zero obligation. Commercial-licensing questions: reach out.

Why 1.5 GB of disk?

That's the on-device brain: a full browser engine plus the ranking and embedding models the cloud services run on their side and bill you for. Disk is cheap; meters aren't.

Homebrew, curl | sh, and the single-file binary are covered in the installation guide — one channel per machine; they all share ~/.wigolo.

Bug reports, feature requests, and PRs are all welcome — see CONTRIBUTING.md. Keep tool handlers thin, add tests, run the suite before opening a PR. The friendliest entry point: wigolo has a plugin system for custom search engines and extractors — add a search engine in ~100 lines, template in examples/plugin-search-engine.

GNU AGPL-3.0-only. Free to use, modify, and self-host — including inside a company. The one obligation: if you run a modified version as a network service, you must publish your modified source under the same license. That keeps wigolo open while preventing a closed, hosted fork. See SECURITY.md to report a vulnerability and TRADEMARK.md for use of the name. For commercial-licensing questions, reach out.

wigolo is free and meant to stay that way — maintained, not paywalled. If it saves you a metered search bill, a ⭐, a sharp issue, or a ☕ coffee helps keep it sustainable.

Built and maintained by @KnockOutEZ · ktowhid20@gmail.com