liustack/modsearch

What is ModSearch?

ModSearch is a plug‑in that gives large‑language‑model (LLM) chat apps – especially DeepSeek Harness (dsh) – the ability to perform real‑time web searches, X (Twitter) searches, and fetch individual pages. It does this by chaining together a set of free or low‑cost search back‑ends (Firecrawl, Antigravity CLI, Tavily, Exa, Grok, and a built‑in local fetcher) and automatically falling back to the next one when a quota is exhausted or a request fails.

---

Why it matters

Many popular LLMs (DeepSeek, GLM, Claude, etc.) run without direct internet access, which limits their usefulness for up‑to‑date information. ModSearch restores that capability without requiring any API keys or credit‑card sign‑up for the default engine (Firecrawl’s key‑less tier gives 1 000 free credits per month). It lets developers and end‑users ask the model for current news, summarize a blog post, or retrieve a specific page, and receive a structured JSON response with sources and a confidence note.

---

Core features

Feature	What it does
Free‑by‑default web search	Uses Firecrawl’s key‑less tier (1 000 free credits/month) out of the box.
Multiple engines with automatic failover	Antigravity CLI, Tavily, Exa, Grok (X), and a local fetcher can be added; the system rotates keys and switches engines when a quota or error occurs.
Per‑engine key rotation	You can supply several API keys for a single engine; ModSearch will try them in order before falling back.
X (Twitter) search	When the Grok Build tool is installed, ModSearch can query the X corpus, reaching content that typical web indexes miss.
One‑click installation for DeepSeek Harness	npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modsearch@<version> installs the plug‑in directly into dsh.
Works across many chat environments	Also usable in Claude Code, Codex, Pi, OpenCode, and via a CLI (modsearch).
Structured output	Returns JSON that includes the result, source URLs, and an uncertainty field that flags aggregated or low‑confidence information.

---

How it works (high‑level flow)

1. You ask the model a question that needs fresh information or give it a URL.
2. The ModSearch skill detects the request and selects the best‑available engine (starting with Firecrawl).
3. It performs the search or page fetch, handling authentication, rate‑limits, and quota checks automatically.
4. The raw results are returned to the LLM, which synthesises a response and appends a source list and confidence note.

---

Getting started

Installation (quickest path)

# Install as a DeepSeek Harness plugin (the most common use‑case)
npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modsearch@5.10.2

Or via the generic skill installer:

npx skills add liustack/modsearch

The default Firecrawl key‑less engine works immediately – no accounts, no API keys.

Adding extra engines (optional)

# Antigravity CLI – requires a browser sign‑in
curl -fsSL https://antigravity.google/cli/install.sh | bash
agy   # sign in, then exit

# Add a Tavily key (if you have one)
modsearch config set tavily.apiKey <YOUR_TAVILY_KEY>

# Add an Exa key
modsearch config set exa.apiKey <YOUR_EXA_KEY>

You can also set keys via environment variables (TAVILY_API_KEY, EXA_API_KEY, FIRECRAWL_API_KEY).

Basic usage

After installation you don’t need to run any commands. Just chat:

• “Summarise the latest AI news.” → ModSearch runs a web search, aggregates six recent stories, and returns a JSON with sources and an uncertainty note.
• “What does the Node.js release page say about maintenance?” → ModSearch fetches the page, extracts the schedule, and replies with a table and source links.

If you prefer the CLI for testing:

modsearch search "AI breakthroughs 2024"
modsearch read_page https://example.com/blog/post

The CLI mirrors what the skill does behind the scenes.

---

Configuration highlights

• Engine enable/disable – modsearch config set tavily.enabled false
• Key rotation – comma‑separate multiple keys: modsearch config set exa.apiKey key1,key2
• Self‑hosted endpoints – point an engine at a custom URL: modsearch config set tavily.baseURL https://my‑proxy.example.com
• Security – built‑in SSRF guards, DNS‑rebinding protection, and optional blocking of private‑network addresses (see docs/security.md).

All settings are stored in ~/.modsearch/config.json with permissions 0600.

---

Who is it for?

• Developers building AI agents that need up‑to‑date information without paying for a paid search API.
• Users of DeepSeek Harness who want a richer web‑search experience.
• Anyone experimenting with LLM‑driven assistants (Claude Code, Codex, Pi, OpenCode) and needing a plug‑in that works out of the box.

---

Limitations & caveats

• The free tiers have monthly credit limits (e.g., 1 000 Firecrawl credits). When exhausted, ModSearch falls back to the next engine, but overall throughput is bounded by the combined free quotas.
• X (Twitter) search requires the Grok Build tool and a valid X Premium or SuperGrok subscription.
• The repository does not accept pull requests; contributions are limited to issues or personal forks.

---

Where to learn more

• Installation guide – INSTALL.md
• CLI reference – skills/modsearch/references/cli.md
• Engine configuration – skills/modsearch/references/configure.md
• Output schema – skills/modsearch/references/output-schema.md
• Security details – docs/security.md
• Demo screenshots – included in the README showcase the plugin in action.

---

Quick takeaways

• ModSearch is a free, plug‑and‑play web‑search layer for LLM chat apps.
• It bundles several search back‑ends with automatic key rotation and failover.
• Installation is a single command for DeepSeek Harness; the default engine works without any user‑provided credentials.
• The tool returns structured JSON with sources and confidence information, making it easy to build reliable AI assistants.