MCPcopy Create free account
hub / github.com/KnockOutEZ/wigolo

github.com/KnockOutEZ/wigolo

Chat with this repo
repository ↗ · DeepWiki ↗ · release v0.3.1 ↗ · + Follow · compare 3 versions
5,277 symbols 18,560 edges 1,343 files 498 documented · 9% ● updated 46d agobinary-v0.2.1-sd507.1 · 2026-09-08★ 5,44742 open issues

Browse by type

⨍ Functions 4,171◇ Types & classes 1,106
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

wigolo — the go-to web for your agent

Local-first web intelligence for AI agents — no keys, no cloud, no metered bill.

works with  Claude Code · Cursor · Codex · Gemini CLI · OpenCode · VS Code · Windsurf · Zed · Antigravity

and beyond  LangChain · CrewAI · LlamaIndex · Vercel AI SDK · n8n & self-hosted agents · any MCP client · plain REST

npm npm downloads GitHub stars CI node MCP license status follow on X Discord

wigolo on Trendshift KnockOutEZ%2Fwigolo | Trendshift

sponsored by

TestMu AI

Quickstart · Tools · Why wigolo · Discord · Sponsors · Benchmark · Docs · Examples · Licensing · Feedback · FAQ

Join the community on Discord — questions, help, and what's being built next.

New features and updates ship steadily. Follow @yourtowhid on X for all of it and new ways to use wigolo, and reach out there for collaborations or feedback · also on LinkedIn


wigolo gives an AI agent one 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 no bill grows with how much your agent thinks.

wigolo demo — Claude Code answering a live web question through wigolo, no API keys

Quickstart

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

Requires Node ≥ 20 and ~1.5 GB of free disk on macOS, Linux, or Windows. Bare init sets up the local engine: it downloads the browser engine and on-device models, runs a health check, and reports each component. Adding --agents wires the named agents in the same run, so a coding agent you use daily is ready in one command.

  • Supported agents — --agents takes any of claude-code · cursor · codex · gemini-cli · opencode · vscode · windsurf · zed · antigravity (comma-separated); wigolo writes the MCP config and, where supported, instructions for each.
  • Any other setup — any MCP client, agent framework, or self-hosted agent registers npx -y wigolo in its own MCP config. The installation guide has the exact config block for every client, plus Docker, Homebrew, and single-file-binary channels.
  • More on the way — the supported list keeps growing, and a PR to add your agent is welcome; see CONTRIBUTING.md.
  • Interactive setup — --interactive is a plain-text flow; --wizard is the full terminal TUI.
  • Defer downloads — --no-warmup waits until first use. A failed component download never fails setup; init reports what's not ready with the exact fix and still completes.

init is unattended by default, so it's safe in scripts and CI, and any setup problem surfaces right here in the per-component report, before your agent's first call. Search, fetch, crawl, extract, cache, and find-similar work with no API key. Check it's healthy anytime:

npx wigolo doctor

To remove everything cleanly, run npx wigolo config --uninstall --yes. You can also paste the installation guide into any AI assistant and let it do the setup; it's written to be self-contained.

Recommended — a free key for research & agent

Search, fetch, crawl, extract, cache, and find-similar are fully keyless. 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. A free Gemini key turns that into a finished answer:

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 are in the configuration guide.

What your agent gets back

Every search result is evidence the agent can act on. It 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):

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

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

Tools

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. Scope by domain and time range, match an exact phrase, or return image results.
📄 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. Handles PDFs, a single-heading section, authenticated sessions, and page actions (click / type / scroll / screenshot).
🕸️ 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. Per-tool guides with the full parameter set are in docs/tools.md; runnable examples are in examples/.

Why it's different

wigolo isn't a free stand-in for the paid tools — it's built to match them. It's a focused web layer for your agents: an MCP and REST surface they call directly, with the search and extraction quality the paid services charge for. What separates it:

  • Built for agents. One MCP call fans out many queries across many engines in parallel, which a serial host tool-loop can't replicate. Every result carries transparent per-result scoring, and output is budget-aware.
  • Honest output. Stale cache, failed fetches, degraded backends, and truncation are surfaced in the result. When a bot-protected page can't be read, you get a labeled blocked_by_challenge failure, not a challenge shell returned 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.

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

Anatomy of a wigolo result: explainable score decomposition, live engine telemetry, surfaced degradation, self-flagged junk — one real query, captured live

Benchmark

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 ran live inside a single Claude Fable 5 session, fanned out to four web tools on equal footing (built-in WebSearch, wigolo, Tavily, Exa), and was judged by the agent on the evidence alone. All four converged on the same answer and the same top source, so the parity is demonstrated on-screen. wigolo alone returned verbatim excerpts pinned to byte-offset source spans, an explainable score decomposition, and live per-engine telemetry, and its own scorer flagged two weak results as junk. The cloud tools earn their place too: Exa rendered the official docs' comparison matrix in full. Run your own query and you'll see the same shape.

wigolo vs built-in WebSearch, Tavily, and Exa on one real query, driven by Claude Fable 5

How it compares

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 compounds, because agents ask in bursts:

The meter: a metered cloud API's cost climbs with every query while wigolo stays flat at zero dollars — illustrative pricing

Beyond your editor

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

REST API — wigolo serve

One process exposes a plain-JSON REST API next to the MCP transport. No MCP client needed, just curl:

```bash 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: applicati

Extension points exported contracts — how you extend this code

browse all types & interfaces →

Core symbols most depended-on inside this repo

browse all functions →

Shape

Function 3,474
Interface 791
Method 697
Class 315

Languages

TypeScript92%
Python8%
Ruby1%

Modules by API surface

src/types.ts81 symbols
src/fetch/browser-pool.ts61 symbols
src/fetch/router.ts58 symbols
src/cache/store.ts51 symbols
src/fetch/cdp-direct.ts49 symbols
src/cli/tui/state/propagation.ts48 symbols
src/extraction/brand.ts43 symbols
src/cli/doctor.ts43 symbols
src/fetch/tls-tier.ts39 symbols
src/cli/tui/config-writer-json.ts35 symbols
src/daemon/rest/firecrawl-compat.ts31 symbols
src/search/core/engine-base.ts29 symbols

Dependencies from manifests, versioned

@anthropic-ai/sdk0.91.1 · 1×
@google/genai1.51.0 · 1×
@iarna/toml2.2.5 · 1×
@inkjs/ui2.0.0 · 1×
@inquirer/prompts7.10.1 · 1×
@modelcontextprotocol/sdk1.29.0 · 1×
@mozilla/readability0.6.0 · 1×
@seriousme/openapi-schema-validator2.9.0 · 1×
@types/cli-progress3.11.6 · 1×

For agents

$ claude mcp add wigolo \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

Ask about this repo answers extend the page