This article is derived from the plugin's already-indexed fields (wiki / faq / compatibility_json / readme), not freshly generated by AI. Source field is noted at the end of each section.

Quick start

modsearch

— source: plugin_wiki.wiki_content

Install & verify

dsh plugin --profile web add @liustack/modsearch

Run the command above in your DSH Web Profile. Then enable the plugin in the plugin list.

— source: plugins.install

Key points

• Completely free. The default channel is Antigravity CLI, no API key needed. All three fallback channels (Tavily, Exa, Firecrawl) offer monthly free tiers with no card required.
• Automatic failover. When a channel fails or exhausts its quota, the next one takes over.
• Searches X (Twitter). With Grok Build installed, ModSearch queries the corpus that web indexes cannot reach.
• Install once, use everywhere. Works in Claude Code, Codex, Pi, and OpenCode.
• Open an issue. Bugs, suggestions, confusing errors, unclear docs. Issues are read and shape what gets built next.

— source: plugin_wiki.readme_en (fallback readme_raw)

FAQ

Can modsearch be used directly after installation, or does it need an API key configured?

Single-page scraping (-u) works with zero config; web search (-q) requires at least one search engine. It defaults to Antigravity CLI (no key needed, log in to browser once), and the three backup engines Tavily/Exa/Firecrawl all have free quotas and don't require a card on file. When nothing is configured, the error message will list all available activation methods.

What changes will there be in dsh after installation?

The native web_search tool keeps its name, and the model sees the native schema and citation cards, but the engine chain behind it is replaced with modsearch; additionally, two tools that dsh doesn't have appear: x_search for searching X and read_page for focused single-page reading, which directly appear in the model's available tools list.

Which account's quota will be deducted during search? Which engine will handle it?

When -e is not explicitly specified, all ready engines form a failover chain in priority order. The results show results[i].engine to indicate the actual responder, attempts lists the trial order, and warnings explain reasons when an engine fails, gets demoted, or hits cooldown - there will never be silent deduction of quota.

Why does the same X question sometimes return content that's not from X?

When Grok Build is not installed, not logged in, or fails this round, the router automatically falls back to the web search engine to answer, and marks the source as web, requestedSource as x, status as degraded, with warnings explaining the fallback reason; it won't pretend to be authentic X results.

How to know what's configured on this machine and what's wrong?

Run modsearch doctor for a pure local check that doesn't consume quota or send network requests. It reports Node version, ready status and reasons for each engine, config source and permissions, private network toggle, and cooldown status. Each unready engine comes with a copyable fix command; add --json for machine-readable output.

What to do when Antigravity CLI reports quota is exhausted?

Quota cooldown failover is enabled by default: this round moves antigravity-cli to the end of the chain, and the next round directly uses other engines first. Wait for weekly reset (the error message will state Resets in ...) or add a configured engine with a key (any of Tavily/Exa/Firecrawl) to restore. modsearch state clear can immediately clear all cooldowns.

How to handle when VPN maps the target address to an internal IP?

Private network/reserved address ranges are rejected by default (SSRF protection). You can allow it once with --allow-private-network, or set it globally with modsearch config set allowPrivateNetwork true. Firecrawl scraping always rejects private network targets, even if the toggle is on.

What will remain after uninstallation?

Simply uninstall this plugin. The only things left on the machine will be ~/.modsearch/config.json (your explicitly configured keys and endpoints) and ~/.modsearch/state.json (cooldown state); no hooks are placed and the host's own configuration is not modified.

— source: plugin_wiki.faq_json

Compatibility

• DSH: 未声明（package.json 无 peerDependencies；通过 dsh.bundle.patch（cordis.patch.yml）注入 dsh 宿主，要求宿主 dsh 暴露 ctx.web.registerSearchProvider / ctx.tools.register）
• Node: >=22.13

— source: plugin_wiki.compatibility_json

Pitfalls

Review the upstream repo before installing. This guide is auto-derived from indexed fields and may lag the latest release. If anything contradicts the official docs, treat the upstream source as authoritative.

— source: general rule