Nole

Nólë

Free web search router for AI agents and coding CLI tools.

Nólë gives Claude Code, Codex, OpenClaw, Hermes, OpenCode and other AI tools a local search/extract layer backed by multiple free or BYOK providers. It is not a hosted SaaS and it is not a replacement for your agent. Keep your existing agent, run Nólë on your own machine or VPS, and make that agent's web search better.

Core idea: use your own keys, keep control of cost, route by task fit and evidence, and return enough routing context for the agent to explain what happened without clutter.

What Nólë is

Nólë is an agent web-search layer:

• A free/local web search router for AI agents and coding CLI tools.
• A BYOK provider router for search and page extraction.
• A task and multi-intent routing substrate for docs, news, code, academic, pricing, fact-checking, social/community and research queries.
• A benchmark/evidence-informed fallback layer for agents that need reliable internet context.
• A small single-binary tool that can be used by humans, shell scripts, MCP clients and agent CLIs.

Nólë is not primarily an MCP server. MCP is one important entrypoint; the product is the local routing layer that MCP, CLI commands and future integrations can call.

Nólë is not:

• A hosted search SaaS or cloud proxy.
• An agent replacement or a research assistant that takes over the workflow.
• A Perplexity clone.
• A provider marketplace.
• A promise of unlimited free search forever.

Why agents use it

Agents and coding CLIs often need web search, docs lookup, URL extraction and source discovery. Nólë lets them delegate that internet layer to a local router that can:

1. Select a route for the task or intent.
2. Prefer free-tier/keyless/BYOK-safe providers by default.
3. Fall back safely when a provider is unavailable, out of quota or returns empty results.
4. Keep provider errors sanitized and avoid leaking secrets.
5. Expose route_trace for debugging and a compact routing insight for user-facing output.

Current routing is task-based with an LLM-free multi-intent planner: nole classify explains detected intents and nole route-plan shows provider routes before any provider call.

Supported and priority agents

Priority v0.1 agent targets:

| Client | Status in this repo | Notes | | --- | --- | --- | | Claude Code | Verified on macOS via claude mcp list/get (M11); see docs/CLIENTS/LIVE-VERIFICATION.md | nole setup --claude prints the official claude mcp add command, including wrapper mode when requested. | | Codex CLI | Verified on macOS via codex mcp list/get (M11); see docs/CLIENTS/LIVE-VERIFICATION.md | nole setup --codex --local-extract inlines ~/.config/nole/.env sourcing in TOML output and prepares local Scrapling; --mcp-wrapper emits wrapper-direct config. | | OpenCode | Verified on macOS via opencode mcp list (M11); see docs/CLIENTS/LIVE-VERIFICATION.md | nole setup --opencode writes OpenCode's native {type, command, enabled, environment} schema. | | Kimi | Verified on macOS via kimi mcp list and kimi mcp test (M11); see docs/CLIENTS/LIVE-VERIFICATION.md | nole setup --kimi writes the same shape that kimi mcp add produces. | | OpenClaw | Verified on OpenClaw 2026.5.18 via the Gateway/agent MCP path; compatibility re-checked on OpenClaw 2026.5.27 with the wrapper-backed MCP registry; see docs/CLIENTS/LIVE-VERIFICATION.md | Run nole setup --local-extract, then configure OpenClaw with openclaw mcp set and the generated env-sourcing wrapper. | | Hermes Agent | Verified on Hermes Agent v0.14.0 via disposable profile MCP path and chat-agent dispatch; v2026.5.28 / v0.15.0 source compatibility reviewed; see docs/CLIENTS/LIVE-VERIFICATION.md | nole setup --hermes --local-extract writes ~/.hermes/config.yaml, prepares local Scrapling, uses the env-sourcing wrapper and preserves unrelated config. | | Cursor | Verified on macOS Cursor 3.4.20 via GUI MCP path and chat-agent dispatch; see docs/CLIENTS/LIVE-VERIFICATION.md | nole setup --cursor --local-extract preserves unrelated MCP servers and emits wrapper-direct config through the generated wrapper. | | Gemini CLI | Repo-tested: the nole setup --gemini writer and config merge are covered by repo tests; the real Gemini CLI was not launched here, so live tool visibility is unobserved. See docs/CLIENTS/gemini.md | nole setup --gemini writes ~/.gemini/settings.json with an object-keyed mcpServers entry, merging only the nole server and preserving sibling servers and unknown root keys. | | Grok CLI | Repo-tested: the nole setup --grok writer and array upsert-by-id are covered by repo tests; the real Grok CLI was not launched here, so live tool visibility is unobserved. See docs/CLIENTS/grok.md | nole setup --grok writes ~/.grok/user-settings.json with an mcp.servers array, upserting the id == "nole" entry in place (or appending) and preserving other servers and unknown root keys. |

A client is only called verified after config path, tool visibility and doctor --mcp behavior are checked without printing credentials.

See docs/CLIENTS/README.md for the client support matrix, docs/AGENT-INSTALL.md for an agent-readable install/handoff checklist, docs/CLIENTS/LIVE-VERIFICATION.md for M11 live-client evidence and docs/INTEGRATION-VERIFICATION.md for the offline/CI integration evidence record.

Providers

Nólë currently supports these provider adapters:

• Brave Search API: web search plus dedicated news/factcheck search, BYOK/free-tier capable.
• Tavily: search + extract, BYOK/free-tier/premium-capable depending on your account.
• Firecrawl: search + extract; keyless API mode works without a key, BYOK/free-tier/premium-capable with FIRECRAWL_API_KEY.
• DDGS: keyless search fallback (the last-resort general fallback on every search route).
• Wikipedia/MediaWiki: keyless encyclopedic search via the official MediaWiki Action API. Reinforces the factcheck, people, and academic routes only (tried before the DDGS backstop); it is deliberately not a general fallback. No key, no setup.
• arXiv: keyless academic search via the public arXiv Atom API. Reinforces the academic route only (tried before the DDGS backstop), with primary-source scholarly preprints; it is deliberately not a general fallback. No key, no setup.
• Scrapling: optional local Python URL extraction fallback. nole setup --local-extract creates an isolated venv, installs scrapling[fetchers] there and writes NOLE_SCRAPLING_PYTHON locally. Nólë does not vendor or redistribute Scrapling.
• httpfetch: keyless pure-Go URL extraction backstop — the last-resort extract fallback (the extract-side analogue of DDGS), always available with no key and no setup. Pure stdlib HTTP fetch + HTML-to-text; runs no JavaScript, so it is weaker than Scrapling/Firecrawl on SPA pages. It makes extract / search_and_extract work out of the box.

Nólë reads provider credentials from environment variables. It should only report whether a key is present; it must never print key values, auth headers or raw provider payloads.

See docs/PROVIDER-KEYS.md for provider-by-provider setup and overage cautions.

Quick start

Prerequisites:

• Go 1.25+ for building from source (matches the go 1.25.11 directive in go.mod).
• Optional provider keys for Brave, Tavily and Firecrawl.
• Optional Python 3.10+ runtime for nole setup --local-extract, which prepares the local Scrapling extraction fallback.
• No provider key is required for the deterministic benchmark, the DDGS, Wikipedia, or arXiv keyless searches, the keyless httpfetch extraction backstop, or a configured local Scrapling fallback.

Build and run locally:

git clone https://github.com/dorukardahan/nole.git
cd nole
go test ./...
go build -o nole .
./nole doctor
./nole doctor --mcp

Try the CLI:

./nole providers --json
./nole bench --json
./nole classify "OpenAI API docs pricing and latest changelog" --json
./nole route-plan "OpenAI API docs pricing and latest changelog" --json
./nole search "Go net/http Client Timeout documentation" --task docs --json
./nole search "latest AI regulation news" --task news --country us --search-lang en --freshness week --json
./nole extract "https://go.dev/doc/" --json
./nole config dump --json
./nole doctor --json

Search, extract, classify and route-plan JSON responses include a short routing_insight by default; search, extract and route-plan keep detailed route_trace for debugging where available. search_and_extract keeps per-URL extract_errors non-fatal, and those partial errors include sanitized routing_insight so agents can see where the failed extract stopped without parsing logs. Human search/extract output prints the same one-line insight before results. Use --insight off to omit the user-facing insight, or --insight verbose to print the compact line plus route trace lines in human output. The insight is deterministic and sanitized; it should not contain API keys, auth headers, raw provider payloads or private URLs.

Search options

The search and research surfaces expose one small typed option set for caller-controlled locale, safety and recency hints:

| Field | CLI flag | Meaning | | --- | --- | --- | | country | --country | two-letter search country code, such as us or tr | | search_lang | --search-lang | search-result language/locale hint, such as en | | ui_lang | --ui-lang | provider UI locale/language hint, such as en-us | | safesearch | --safesearch | off, moderate, or strict | | freshness | --freshness | pd/day, pw/week, pm/month, or py/year |

REST accepts these under an optional options object on /api/search, /api/search_and_extract, and /api/research; MCP exposes the same semantic fields as optional top-level tool parameters on search, search_and_extract, and research. For research, options apply only to the internal search passes; extract steps remain URL-only.

Nólë prevalidates/canonicalizes options in core.Service before routing. Invalid caller values fail as request errors; provider calls are not attempted. The response cache keys the canonical option set, so a localized/freshness/safe search request cannot collide with the same query using default options.

Provider support is intentionally conservative: Brave forwards all five fields on the Search-plan Web/News endpoints; Tavily and Firecrawl forward only country plus a freshness/time-window mapping; DDGS, Wikipedia, arXiv and extract-only providers ignore unsupported options. Nólë does not emulate unsupported behavior, fabricate rankings, or use Brave Answers/chat-completions for this surface.

Install a prebuilt release binary with the install script — it detects your OS/arch, downloads the matching asset, verifies its SHA256 checksum before installing (fails closed on mismatch), and installs to ~/.local/bin. Download-and-read first (recommended), then run:

curl -fsSLO https://raw.githubusercontent.com/dorukardahan/nole/main/scripts/install.sh
less install.sh   # read it before running
bash install.sh
nole doctor

NOLE_INSTALL_VERSION pins a tag and NOLE_INSTALL_DIR overrides the location. SHA256 is the mandatory integrity floor (fail-closed). Since v0.10.0 releases also carry keyless [build-provenance attestations](docs/PACKAGING.md#checksums-and-signing); when the GitHub CLI (gh >= 2.93.0) is present the installer additionally verifies the attestation, and NOLE_INSTALL_VERIFY=require makes that verification mandatory. Absence of gh is a graceful skip, so the zero-dependency path still installs on SHA256 alone.

Windows has its own PowerShell installer with the identical verification model (SHA256 floor + additive gh attestation verify, same NOLE_INSTALL_* overrides):

irm https://raw.githubusercontent.com/dorukardahan/nole/main/scripts/install.ps1 | iex

Download-and-read first (recommended): irm https://raw.githubusercontent.com/dorukardahan/nole/main/scripts/install.ps1 -OutFile install.ps1, read it, then powershell -ExecutionPolicy Bypass -File .\install.ps1. It installs to %LOCALAPPDATA%\Programs\nole and adds it to your user PATH. (Or download the nole-windows-.exe asset from the releases page manually.)

Homebrew (macOS + Linux):

brew install dorukardahan/nole/nole

The formula installs the same prebuilt release binary and pins its SHA256 (Homebrew's integrity check). See docs/PACKAGING.md for the tap details.

Scoop (Windows):

scoop bucket add nole https://github.com/dorukardahan/scoop-nole
scoop install nole

The manifest installs the same prebuilt nole-windows-.exe release asset and pins its SHA256 (Scoop's integrity check). See docs/PACKAGING.md for the bucket details.

Or install a locally built binary by hand:

mkdir -p ~/.local/bin
cp ./nole ~/.local/bin/nole
export PATH="$HOME/.local/bin:$PATH"
command -v nole
nole doctor
nole doctor --check-updates   # fail-soft notice if a newer release exists; silent offline

If the agent/client process does not inherit PATH, use /absolute/path/to/nole in the MCP config.

Optional, but recommended for agent installs that should expose URL extraction without provider keys:

nole setup --local-extract
nole doctor --mcp

This creates ~/.local/share/nole/scrapling-venv, installs Scrapling into that isolated Python environment, writes ~/.config/nole/.env, and generates an env-sourcing MCP wrapper at ~/.local/bin/nole-mcp.

Configure an agent when the setup writer is available:

nole setup --claude
nole setup --codex
nole setup --hermes
nole setup --opencode
nole setup --codex --local-extract
nole setup --hermes --local-extract
# see `nole setup --help` for the full client list (cursor, kimi, windsurf, gemini, grok, etc.)

For unverified or generic clients, use the MCP command template:

{
  "mcpServers": {
    "nole": {
      "command": "/absolute/path/to/nole",
      "args": ["mcp"]
    }
  }
}

Provider keys and cost control

Default stance: free-first. Nólë treats supported keyed provider accounts as free-tier-BYOK by default and tracks a hardcoded monthly free quota locally (currently 1000 calls/month for Brave, 500 for Tavily, and 250 for keyed Firecrawl, reset at the start of each UTC calendar month — the lower floors reflect those providers' variable per-credit metering, where the ledger debits 1 per call but an advanced Tavily call costs 2 credits and a 20-result Firecrawl search costs 4). Firecrawl without FIRECRAWL_API_KEY, DDGS, Wikipedia, arXiv, the keyless httpfetch extraction backstop, and a configured local Scrapling runtime are keyless-free: no local free-tier quota ledger, no hidden paid usage inside Nólë, and no claim that Nólë knows remote balance. Keyless remote providers can still be shared, rate-limited or unavailable upstream; Nólë reports those 429/provider errors as route/provider drift, not as local ledger exhaustion.

A key by itself is enough to start using a provider under the default policy; you only have to flip NOLE__PAID=1 when you want Nólë to treat that provider as premium-capable (e.g. you are on a paid plan and the cost-capped or quality-first policy should apply). See docs/PROVIDER-KEYS.md for per-provider free-tier sourcing and the Brave subscription/CC caveat.

Cost status classes exposed in provider_status, budget_status, route_trace and JSON CLI/MCP surfaces are:

• keyless-free — no key required, currently used for the DDGS search fallback, the Wikipedia/MediaWiki and arXiv search providers, the keyless httpfetch extraction backstop, and the optional local Scrapling extraction fallback.
• free-tier-BYOK — user-keyed provider running against the local free-tier quota. Default for keyed Brave / Tavily / Firecrawl.
• premium-capable — keyed pr

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dorukardahan
• Source: dorukardahan/nole
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.