Wiggle‑on‑the‑Web: What wigolo Does

TL;DR

• wigolo is a local‑first, zero‑key‑cost‑by‑default ​ web‑toolkit for AI‑agents.
• It bundles search, fetch, crawl & extract plus higher‑level research and autonomous‑gather loops that an agent‑orchestrator (Claude 5 Fable …​) can call via **MCP JSON‑RPC over stdio ** or REST.
• All search‑engine‑agnostic ​ work‑flows ​‑ 18‑engine fusion‑fetched ​‑ ML‑reranked ​‑ explainable ​‑ cached ​‑ offline ​‑ private **​.
• Optional LLM synthesis (Gemini, Anthropic, OpenAI, Groq, Ollama) turns raw evidence into a finished answer.
• Runs on Node ≥ 20 (≈1.5 GB disk) on macOS, Linux or Windows; ships as an npm CLI, Docker image, SDKs (TS/​Python) and MCP server.

---

What It Actually Is

Aspect	Details
Category	Local‑first web‑intelligence layer for AI agents (search, fetch, crawl, extraction, caching, similarity, research, autonomous loops).
Primary Interface	MCP (JSON‑RPC over stdio) – the same protocol used by coding‑agents like Claude Code, Cursor, Codex, Gemini CLI, etc.
Secondary Interfaces	REST API (wigolo serve), TypeScript & Python SDKs, Docker container, framework wrappers (LangChain, CrewAI, LlamaIndex, Vercel AI SDK).
Key Claims	• No API keys required for core tools (search/fetch/crawl/…); • $‑free‑per‑query ‑ all caching is local; • Evidence‑rich results with byte‑exact citations and explainable scoring; • Works offline after the initial download of a head‑less‑browser engine & on‑device models.
Supported Agents	Claude Code, Cursor, Codex, Gemini CLI, OpenCode, VS Code, Windsurf, Zed, Antigravity (any MCP client can be added).
Installation	npx wigolo init (downloads browser engine & on‑device models), optional --agents to auto‑wire agents, --interactive/--wizard for guided setup, wigolo doctor to verify health.
Core Tools	search, fetch, crawl, extract, cache, find_similar, research, agent, diff, watch.
Result Shape	JSON containing results (title, url, excerpt, citation_id, source_span, evidence_score), citations, and freshness signals.
Privacy	All cache, embeddings, and models live under ~/.wigolo/; nothing is sent to third‑party services unless you enable an LLM provider.
Licensing	AGPL‑3.0 (see LICENSING.md).
Status	Public beta ​— actively maintained (CI badge, star history, Discord community).

---

How It Works (Simplified)

1. Agent → wigolo – An AI‑agent makes an MCP/REST call like search {query:"…"}.
2. Tool Layer – wigolo fans‑out the request to many web‑engine adapters (18 engines), merges results, runs an on‑device ML reranker, and attaches a transparent score.
3. Fetch Router – For URLs, wigolo first tries a plain HTTP fetch; if a bot‑challenge or SPA is detected it escalates to a headless‑browser pool.
4. Cache & Embeddings – Results are stored locally (keyword + vector index) so repeated queries are instant and offline.
5. Optional Synthesis – If WIGOLO_LLM_PROVIDER is set, a chosen LLM rewrites the evidence into a polished answer; otherwise raw evidence is returned.
6. Response – The agent receives a structured JSON with citations, byte‑exact excerpts, scores, and any degradation flags.

---

When Would You Use It?

• You have a coding‑assistant (Claude Code, Cursor, etc.) and want it to browse the web without exposing API keys or paying per‑query.
• You need reproducible, auditable evidence – each snippet is pinned to its exact byte offset and scored.
• You run agents on‑premise (self‑hosted LLMs, private data) and require the web‑layer to stay local.
• You want a drop‑in replacement for cloud web‑search APIs in LangChain, CrewAI, LlamaIndex, etc., with zero‑cost queries.
• You need offline capability after the initial engine download (e.g., in CI pipelines or air‑gapped environments).

---

Quick‑Start Checklist

# 1. Install & initialise (downloads browser & models)
npx wigolo init

# 2. Verify health
npx wigolo doctor

# 3. Try a search from the CLI
wigolo search "local‑first software" --json

# 4. Run the REST server (optional)
wigolo serve   # → http://127.0.0.1:3333

# 5. Use the Python SDK (example)
python - <<'PY'
from wigolo import local_client
with local_client() as c:
    print(c.search(query='local‑first web search')['results'][0]['title'])
PY

---

Limitations & Open Questions

Area	Current State
Coverage of web engines	18 adapters, but some niche or paid APIs may still be missing.
LLM synthesis	Optional and still requires an external key (Gemini free tier, OpenAI, etc.).
Heavy‑weight crawling	Designed for research‑grade volumes; massive enterprise crawls may need a dedicated crawler.
Platform	Node‑based; non‑Node environments must use the REST/SDK bridge.
License	AGPL‑3.0 – may affect commercial redistribution.

---

Where to Find More

• Docs – docs/README.md (installation, CLI, tools, REST, SDKs, self‑hosting).
• Examples – examples/README.md (real‑world agent scripts).
• Community – Discord link, X @yourtowhid.
• Benchmarks – Section in the README compares wigolo against Firecrawl, Exa, and Tavily.

---

All statements above are taken directly from the repository’s README; no additional features have been inferred.