wigolo: Add a Local, API‑Key‑Free Search Brain to Your AI Agent

Installation

wigolo runs on Node ≥20, requires ~1.5 GB disk for the browser engine and local model, and supports macOS, Linux, and Windows. A single command installs all components:

npx wigolo init --agents=claude-code  # or cursor, codex, gemini-cli, etc.

The init command downloads the browser engine, the local model, and configures the MCP client. After it completes, search, fetch, extract, cache, and similarity search work without any API key.

Architecture and Tools

wigolo is a single Node process that communicates with AI agents via the MCP protocol (JSON‑RPC over stdio). It provides ten built‑in tools:

search : queries 18 search engines directly, performs rank‑fusion, re‑ranks results with a local ML model, and assigns explainable scores (semantic relevance, lexical match, consensus).

fetch : hierarchical router that first tries plain HTTP; if the response contains SPA markers or anti‑scraping challenges, it upgrades to headless‑browser rendering. Upgrade decisions are based on observable response content, not domain heuristics. Learned per‑domain rules can be inspected with wigolo tune list; blocked pages are labeled blocked_by_challenge.

cache : stores all fetched pages under ~/.wigolo/ with keyword and vector indexes. Repeated queries hit the cache with zero latency, and embeddings and re‑ranking run locally, keeping data private unless an external LLM is added.

research and agent : research decomposes a question, runs parallel searches, fetches sources, and synthesizes a cited report; agent runs an autonomous loop (plan → search → fetch → extract → synthesize) with a time budget and output schema. Both require an LLM for synthesis; a free Gemini key or Ollama can be used.

Other utilities: crawl (multi‑page crawling with robots.txt and rate‑limit compliance), extract (structured data extraction), find_similar (similar‑page discovery), diff and watch (page‑change monitoring with webhook). All are accessible via terminal, interactive shell, REST API, or TypeScript/Python SDK.

Design Principles

Code‑first, LLM‑second : deterministic tasks such as normalization, deduplication, and rank‑fusion are handled by code; LLMs are only used for answer synthesis, and generated content is verified against the source.

Observable‑signal routing : fetch upgrades are triggered by actual response cues (SPA markers, challenge pages) rather than guessed domain patterns.

Transparent failure reporting : cache misses, fetch failures, or backend degradations are explicitly marked in the result.

Empirical Comparison

A benchmark compared Claude’s built‑in WebSearch, wigolo, Tavily, and Exa on the same query. All four returned the same core answer, but only wigolo supplied the exact source snippet and labeled weak results as “garbage”.

Quick Start

Install Node.js 20+ and run the init command:

Verify the installation:

In Claude Code, ask a networked question such as “latest PostgreSQL 16 release notes”; wigolo automatically performs the search and returns results.

To enable synthesis with a free Gemini key, set the environment variables:

export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<your‑free‑key>

Conclusion

Running a local browser engine plus model costs far less than per‑call APIs and provides advantages in privacy, latency, and customizability. Strictly anti‑scraping sites may still be problematic, but wigolo marks failures instead of fabricating answers. Repository: https://github.com/KnockOutEZ/wigolo