Web Search Plus — Hermes Plugin

Give your Hermes agent better web search and clean page reading. Web Search Plus connects several search services behind one simple setup. It returns the original links and pages, can try another service when one fails, and works with just one configured provider.

It adds two Hermes tools:

web_search_plus — search the web and return useful sources
web_extract_plus — read and clean the pages you already have

Ported from web-search-plus-plugin for the Hermes Agent plugin API.

Current release: v4.0.1 — see the Changelog. The 4.0.0 DonSeTch migration notes remain in 4.0.0 Release Notes.

What's new in 4.0.1

DonSeTch now reuses one stdio MCP session for every URL in a single extract call, reaps the child on timeout or MCP failure, and reports binary readiness from setup.py status. Search and Extract stay explicit-only.

What's new in 4.0.0

Web Search Plus now uses DonSeTch 2.1.0 as its optional local source provider for Search and Markdown Extract. DonSeTch runs as a separately installed stdio MCP process configured through DONSETCH_BIN; it is not bundled with this plugin. The Hound provider and HOUND_MCP_URL integration were removed, so this release includes a migration step for existing Hound users.

For technical details, see the Changelog, provider guide, and 4.0.0 Release Notes.

Why use it

One setup, many search services. Pick one provider to start and add more only when you need them.
Real sources. Results point back to the pages they came from instead of hiding the web behind a generated answer.
Fewer dead ends. If one service is unavailable or returns nothing, Web Search Plus can try another.
Search and page reading together. Find useful pages, then turn them into clean text for your agent.
Optional details when you need them. Quality reports show which service worked and what happened along the way.
Local options are available. SearXNG, Keenable and the optional DonSeTch provider can reduce your dependence on paid APIs.

Everything new since 3.0 is additive or opt-in, except the v4.0 provider migration described above. Full details: 4.0 Release Notes · 3.4 Release Notes · 3.3 Release Notes · 3.2 Release Notes · 3.1 Release Notes · 3.0 Release Notes.

Quick Start

# 1) Install and enable the plugin
hermes plugins install robbyczgw-cla/hermes-web-search-plus --enable

# 2) Inspect provider readiness and configure the providers you use
python3 ~/.hermes/plugins/web-search-plus/setup.py status
python3 ~/.hermes/plugins/web-search-plus/setup.py setup --preset starter

# 3) Reload Hermes so the tools are registered
# CLI: exit and start `hermes` again, or use /reset in-session
# Gateway: /restart, then /reset

# 4) Optional shell smoke test
cd ~/.hermes/plugins/web-search-plus
python3 search.py --query "Hermes Agent latest release" --provider auto --quality-report

Web Search Plus supports 15 search and 9 extraction providers — you do not need them all. One search-capable key or configured local endpoint enables web_search_plus; one extraction-capable key or endpoint enables web_extract_plus; more providers just make controlled routing more flexible. The setup helper stores keys in the active Hermes environment file — never commit them to the repository.

Provider privacy is not uniform. Before sending sensitive queries or URLs, review the maintained Provider Privacy & Terms guide, which distinguishes standard self-serve terms from enterprise-only ZDR or no-training options.

Upgrading to 4.0.0

The core tools and existing keyed providers remain available, but the optional Hound integration was removed. If you used Hound, follow the DonSeTch migration guide: install DonSeTch 2.3.1 separately, set DONSETCH_BIN, and change explicit provider="hound" calls to provider="donsetch".

Self-hosted / no-paid-key profile

For a privacy- and budget-oriented setup with no commercial API key, use the self-hosted wizard preset:

python3 ~/.hermes/plugins/web-search-plus/setup.py setup --preset self-hosted
python3 ~/.hermes/plugins/web-search-plus/setup.py status

It selects the derived self_hosted profile: automatic search uses only your SearXNG instance and keyless Keenable, while automatic extraction runs through Keenable's public fetch tier (SearXNG does not extract; the public tier is rate-limited and has no SLA). Configure SearXNG with searxng.base_url (the older instance_url still works); the preset enables Keenable's existing public tier without writing a key. See the Self-hosted profile guide for prerequisites and explicit-provider behavior.

Optional Octen source search via Monid

Set MONID_API_KEY from Monid to use Octen as an explicit source-search provider:

web_search_plus(query="recent vector database research", provider="octen", freshness="month")

The adapter executes Octen's /search endpoint through Monid's documented HTTP API for ranked links and highlights. It supports freshness and domain filters, explicitly disables full-content retrieval, and does not call Octen's answer or Broad Search APIs. Access and billing use Monid's prepaid wallet; see Monid for current pricing and terms. Octen stays outside automatic routing and fallback unless you deliberately enable auto_allow.

Optional TinyFish source search

Set TINYFISH_API_KEY from your own TinyFish account to use its direct Search API explicitly. Web Search Plus does not provide, pool, proxy, or share TinyFish credentials.

web_search_plus(query="recent agent framework releases", provider="tinyfish", freshness="week")

The adapter calls only TinyFish's fixed source-search endpoint and returns ranked links and snippets. It never sends the optional purpose or fetch parameters and does not call TinyFish Agent or Browser APIs. Domain filters and result hosts are accepted only as ASCII/Punycode hostnames; raw Unicode hostnames are rejected fail-closed. TinyFish remains outside automatic routing and fallback: its standard Terms permit Customer Data to be used for model training and fine-tuning, and its Privacy Policy does not provide a fixed deletion period. Treat the integration as high risk unless your contract supplies stronger terms; see the provider/privacy matrix.

Local DonSeTch provider

DonSeTch is an independent AGPL-3.0-only local MCP program for source search, fetching, crawling, and PDF-oriented retrieval. WSP 4.0 connects to a separately installed DonSeTch executable through stdio; it does not bundle or redistribute DonSeTch. DonSeTch is explicit-only by default, so installing it does not change automatic routing or fallback.

Set DONSETCH_BIN to the absolute executable path and see the DonSeTch provider guide for installation, migration, security boundaries, verification, and limitations.

Update later with:

hermes plugins update web-search-plus

Python 3.10+ is required for the core plugin. The optional DonSeTch bridge uses the separately installed executable and does not add DonSeTch or its AGPL-3.0-only dependencies to the plugin package.

The two tools

`web_search_plus`

Use it for current information, source discovery, or opt-in multi-provider research.

web_search_plus(query="Hermes Agent latest release")
web_search_plus(query="compare recent open-source agent frameworks", mode="research", quality_report=True)

`web_extract_plus`

Use it when you already have URLs and want clean page content.

web_extract_plus(urls=["https://example.com"])
web_extract_plus(urls=["https://docs.example.com"], provider="linkup", render_js=False)

Full parameters, freshness and locale behavior, provider selection, extraction controls, and cache management live in the User Guide.

Documentation

Where to go next:

Installing or configuring providers → User Guide · DonSeTch local provider
Comparing provider privacy and terms → Provider Privacy & Terms
Upgrading to 4.0.0 → DonSeTch migration
What changed → Changelog · 4.0 Release Notes
Troubleshooting → FAQ · Operator Console
Contributing or building a provider → Contributing · Provider SDK · Architecture

The full reference, including the normative v3 contracts for implementers and reviewers:

Start & upgrade

User Guide — installation, first-run checks, tool usage, and troubleshooting
3.4 Release Notes — optional Octen source search via Monid, access/billing, security, and compatibility
3.3 Release Notes — heading-aware spans, provenance enrichment, Research quorum, compatibility, and attribution
4.0 Release Notes — DonSeTch integration, Hound removal, migration, and limitations
DonSeTch local provider — separate installation, stdio configuration, migration, and operating boundaries
3.1 Release Notes — 3.1 highlights and compatibility
3.1 Migration — opt-in matrix, kill switches, verification, and rollback
Provider SDK — add a provider with one providers.d module
3.0 Release Notes — highlights, provider changes, compatibility, and 3.1 deferrals
3.0 Migration — dry run, apply, smoke tests, and rollback
3.0 Compatibility and Backup & Restore — stable surfaces and recovery behavior

Configure & operate

Provider Reference — generated capabilities, environment variables, defaults, and signup links
Provider Privacy & Terms — provider-specific training, retention, ZDR, and contract caveats
Routing v2 Reference — generated routing classes, preferences, and demotions
Operator Console — local read-only visibility and troubleshooting
Provider Benchmarks — search and extraction comparison with privacy and quota guidance
FAQ — provider selection, cache, cost, and common setup problems

Deep reference

Architecture — plugin boundaries, routing, cache/state flow, and provider extensions
3.0 Wire Contract — normative request and response surface
Source Evidence, Bounded Context, and Search Parity — detailed v3 contract amendments

Development

cd ~/.hermes/plugins/web-search-plus
python3 -m pip install -r requirements.txt
python3 -m pytest -q
python3 -m compileall -q __init__.py search.py setup.py scripts tests

Generated provider and routing references are checked in CI. Start with Contributing; development architecture and extension notes are in Architecture.

License

MIT — see LICENSE.

web-search-plus-plugin — TypeScript/OpenClaw version
Hermes Agent — the agent runtime this plugin extends
DonSeTch — independent AGPL-3.0-only local web-research MCP program; WSP integrates through a separate stdio process

hermes-web-search-plus