Modsearch

What ModSearch is

The package is @liustack/modsearch, published at version 5.10.2 by Leon Liu under the MIT licence. The repository brands it as “the strongest free web search plugin for DeepSeek Harness (dsh)”, and the pitch is narrow and testable: models like DeepSeek and GLM have no web access or a weak one, so this plugin supplies web search, X search, and single-page fetch. In dsh the plugin presents a settings card under Settings → Plugins → Plugin config.

Note what is not claimed here: the README does not say the plugin performs best in any measured comparison, and it publishes no benchmark. Treat the “strongest” line as the author’s positioning, not a verified result.

What you install: read the manifest, not the slogan

Two fields decide what you actually get, and both are unusual enough to spell out.

The top-level dsh field declares a Cordis bundle: bundle.patch points at ./cordis.patch.yml, which the harness applies when the package mounts. It also declares a client half — platform: "web", client.inject: [], immediately: true — meaning a web-platform client bundle that activates immediately and needs no injected service. The README confirms one visible consequence: there is a ModSearch card in the dsh settings page. The README does not describe what the patch rewrites, and the patch file itself is not part of the sources for this listing, so the exact edit is unstated.

The files array is the honest inventory of the tarball: dist, docs, skills/modsearch/SKILL.md, skills/modsearch/scripts, skills/modsearch/references, CHANGELOG.md, SECURITY.md, dsh, and cordis.patch.yml. So you install three things at once — a CLI, an agent Skill, and the dsh bundle. The package’s two runtime dependencies are commander and undici: a CLI argument parser and an HTTP client, nothing heavier.

What actually backs the search

Every search and fetch is executed by a third-party engine. The default is Firecrawl’s keyless tier and it works with zero setup; the alternatives are the Antigravity CLI, Tavily, Exa, Grok Build (X/Twitter search), and local (page fetch only). Multiple configured engines form a chain with automatic failover.

Keys are optional and live in ~/.modsearch/config.json (created 0600, masked when displayed) or in the environment as TAVILY_API_KEY, EXA_API_KEY, or FIRECRAWL_API_KEY. An engine can take several comma-separated keys, and on authentication, rate-limit, or quota failure the plugin rotates to the next key before falling further down the chain. Engines that speak a Tavily-, Exa-, or Firecrawl-compatible protocol can be pointed at your own endpoint with a baseURL setting; the README says official endpoints stay compiled into the code and are never written out as default config.

This is the trust core, so read it precisely. The plugin’s own code and dependencies (commander, undici) contain no search index; the results come from Firecrawl, Tavily, Exa, Antigravity, or Grok. ModSearch drives those upstreams. The README’s disclaimer says the upstream engines “each carry their own terms and quotas, and complying with them is the user’s responsibility” — that is the whole of what the source says about the upstream relationship.

What the source does not say, and what a reader would otherwise assume: it never states whether requests are proxied through any liustack-operated service or go straight from your machine to the engine’s endpoint, it never states whether ModSearch logs queries, it publishes no retention or telemetry policy, and it never identifies which search index sits behind Firecrawl’s keyless tier. Absence of a logging claim is not evidence that nothing is logged.

What it does

• Web search through the configured engine chain, returned as structured JSON the model can consume rather than scraped markup.
• Page fetch as a separate step, so the model decides when to spend tokens on a full page. The README names a read_page tool that can read more than one page in sequence.
• A stated confidence signal. A demo run returns six sourced stories “with a closing note on which details came from aggregation and deserve a second look”; the README attributes that caveat to the uncertainty field.
• X (Twitter) search, and this is the one to read carefully: it “queries the corpus that web indexes cannot reach” with Grok Build installed. It rides a SuperGrok or X Premium subscription. There is no keyless path to X.
• Failover and per-engine key rotation, plus the ability to exclude an engine outright.
• The dsh settings card for picking a preferred engine, entering a key or a self-hosted endpoint, and ticking which engines join failover. The README’s own install instructions for other harnesses (Claude Code, Codex, Pi, OpenCode) describe a Skill install path; the card is the dsh-specific one.

Requirements — and what “free” actually means

• Node.js 22.13 or newer — declared in engines, so this is a hard floor rather than a suggestion.
• Working outbound network access. Nothing here runs offline, and the local engine covers page fetch, not search.
• No key and no account for the default setup. That matters for web search and page fetch on Firecrawl Keyless.
• An account only if you want more. The Antigravity CLI needs a browser sign-in; Grok Build needs SuperGrok or X Premium. Free Tavily, Exa, or Firecrawl keys are optional.
• The harness floor is unstated in the README. Neither the README nor the manifest declares a harness version, a peer range or a dsh.compatibility block, so this listing records no dshTarget and stops at L2. The README gives no supported-OS list either.
• A proxy or VPN is survivable. The README says Clash, Clash Verge Rev, mihomo, and Surge fake-IP mode works out of the box, because DNS answers in 198.18.0.0/15 are treated as fake-IP placeholders without a switch. Literal URLs such as http://198.18.0.5/ stay blocked while allowPrivateNetwork is off.

Free here means someone else’s free tier, not an unlimited service. Firecrawl Keyless grants 1,000 credits every month with no account, no API key, and no card, and a free Firecrawl key adds a personal 1,000/month on top. Antigravity CLI is free with a browser sign-in. Tavily gives 1,000 credits/month without a card; Exa gives a recurring $10/month credit, which the README characterises as roughly 1,400 searches. Grok Build is not free — it rides a paid SuperGrok or X Premium subscription.

So: no signup and no API key are genuinely true for the default web-search and fetch path, and false for X search. X search needs Grok Build, which needs a paid account.

The arrangement is not guaranteed. Every quota above is an upstream vendor’s published allowance, and the README itself describes the keyless tier as a launch arrangement. If Firecrawl changes, throttles, or ends the keyless tier, the default engine loses its quota and the chain falls to whatever else you configured — which, on a fresh install, is nothing. Credit exhaustion also does not necessarily mean an error: failover is the designed response, so a silent switch to another engine is possible. The source states no uptime or availability commitment of any kind, and no cap on credits consumed per search or per fetch.

Privacy: where your query goes

Your query leaves the machine. On a default install the text you search for is sent to Firecrawl’s keyless service, and the page URLs you fetch are sent to whichever engine serves the fetch. If you add Tavily, Exa, Antigravity, or Grok Build, those see the query instead or as well. What those services do with it is governed by their own terms — the README pushes exactly that responsibility onto the user in its disclaimer.

Two things are documented in the plugin’s favour. Keys are stored in ~/.modsearch/config.json with 0600 permissions and are masked when shown, and the package ships a SECURITY.md plus a security doc mentioning SSRF guards, DNS-rebinding protection, and untrusted-input handling.

What is not stated, and should not be inferred: the README does not claim the plugin is private, does not say whether any liustack-operated intermediary sees your traffic, does not say whether queries or results are logged anywhere, and does not describe what the SSRF and anti-rebinding guards actually cover or where they apply. The package declares no permissions field and this listing is recorded as security: unverified. If you are searching material you would not paste into a third-party web service, do not assume this plugin changes that exposure.

Known limits — and when to use it, and when not to

The README is unusually willing to name failure modes, and they are worth quoting rather than paraphrasing:

• “When a channel fails or exhausts its quota, the next one takes over.” Coverage therefore depends on which engines are configured and still have quota.
• Per-engine key rotation triggers on “authentication, rate-limit, and quota failures” — nothing else.
• The upstream disclaimer: engines “each carry their own terms and quotas, and complying with them is the user’s responsibility.” No warranty is given “for any particular use, commercial or otherwise.”
• Coverage gaps. Only the open web and X are searched. X requires Grok Build. There is no stated engine for other closed platforms, and no statement about index depth, freshness, or language coverage for any engine.
• Product gaps. No OpenSearch-compatible engine, and no integration with browsers or search bars. local is a page-fetch engine, not a search index, so you cannot search anything without a network engine.
• Naming gaps. The README names read_page as a tool but never lists the tool set the dsh bundle registers, so the exact tool names a model will call are unstated. The SKILL.md that a Skill install would load is listed in files but is not included here.
• Independence. The source publishes no third-party security review or malware scan, and the repo “does not accept pull requests” — it is maintained by the author alone. A single maintainer is a sustainability signal, not a defect, but plan for it.
• The source states no star count, no user count, and no install count. This listing’s stars: 471 comes from the directory’s own metadata, not from the package.

Use it when your dsh model cannot reach the web and you want search working in one step with nothing to sign up for. The keyless Firecrawl default is the reason this entry exists: you get real search and page fetch immediately, and the uncertainty field plus per-result citations make the output auditable rather than a black-box summary. If you already pay for Grok, adding X coverage is the one thing here that web indexes cannot replicate.

Do not use it as a substitute for a paid search API when your workload is heavy or must be predictable. The default engines are shared free tiers, failover is silent by design, and nothing in the source promises throughput. Do not use it while believing it is private: your query goes to a third party by construction, and no logging or retention statement exists to say otherwise. And do not install it expecting X search to work out of the box — without Grok Build and a paid subscription, that feature is simply absent.

FAQ

Does X (Twitter) search really work without credentials?

No. The README ties X search to Grok Build explicitly: “With Grok Build installed, ModSearch queries the corpus that web indexes cannot reach”, and the engine table lists Grok Build as riding “SuperGrok or X Premium”. Both are paid. Web search and single-page fetch are the parts that work with no key; X is not one of them.

Is the “no API key” part true?

For the default path, yes, and only there. Search and page fetch run on Firecrawl’s keyless tier with no account, no API key, and no card. Every additional engine, and every key you supply for higher quota, reintroduces a key — stored in ~/.modsearch/config.json or an environment variable.

Is the free quota guaranteed to stay?

No, and the source does not pretend otherwise. The 1,000 credits/month figure comes from Firecrawl’s keyless launch, and the README’s own disclaimer says each upstream engine carries its own terms and quotas. Nothing in the package lets the author promise someone else’s allowance will persist.

Does my search query stay on my machine?

No. The query is sent to the engine that serves it, which on a default install is Firecrawl’s keyless service, and page URLs go to whichever engine performs the fetch. The README does not state whether an intermediary sees the traffic, whether anything is logged, or what the retention policy is. Keys at least are stored 0600 and masked in output.

What exactly gets installed?

The npm package @liustack/modsearch@5.10.2: a CLI binary named modsearch, an agent Skill under skills/modsearch, and a dsh bundle declared by the top-level dsh field (bundle.patch: ./cordis.patch.yml plus a web client half). Its runtime dependencies are commander and undici. The Cordis patch file itself is not among this listing’s sources, so what the patch edits is not asserted here.