ModSearch skill
A skill for web search, X search and page fetching for models without web access: no signup or key, the answer is JSON with source links
- 815 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The skill runs shell commands: it downloads the @liustack/modsearch package through npx or bunx and executes it on the machine
- Search queries and addresses of public pages go to external services, first of all Firecrawl and Keenable
- Optional API keys sit unencrypted in `~/.modsearch/config.json`, protected only by file permissions
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/modsearchDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The skill runs shell commands: it downloads the @liustack/modsearch package through npx or bunx and executes it on the machine
- Search queries and addresses of public pages go to external services, first of all Firecrawl and Keenable
- Optional API keys sit unencrypted in `~/.modsearch/config.json`, protected only by file permissions
This is third-party code. Review the repository files before installing.
What it does
ModSearch gives an agent web search, X search and single-page fetching where the model has no web access of its own, for example DeepSeek or GLM. The skill triggers when a question needs fresh data, source links, posts from X or the content of a specific address and the agent has no built-in tool. The agent runs the `modsearch` command through the launcher script in the skill folder and gets JSON: a summary per source, a list of found pages with title, address and snippet, and two caveat lists, `uncertainty` with doubts about the facts and `warnings` with the route the request took. Engines are picked per task. Web search goes through Firecrawl, and Keenable, Antigravity CLI, Tavily and Exa take over on a failure or an exhausted quota. Pages are read by Firecrawl, Antigravity CLI or the built-in local fetcher. X search is possible only through Grok Build. An engine that ran out of quota moves to the end of the queue until it recovers, and the answer shows which engine replied. Firecrawl and Keenable work with no setup.
Who it is for. For people running Claude Code, Codex, OpenCode or Pi on models with no search of their own who want sourced answers without a paid key.
Good fit when
- The agent runs on DeepSeek or GLM through the API and cannot find anything online by itself
- You need fresh versions, prices or news with links to primary sources
- You want to know what people post on X about a topic and you have SuperGrok or X Premium
- The agent got a page address and must summarize it, and there is no page reading tool
- Built-in search pulls whole pages into the context and you want short structured data: in Codex the author measured about 30,000 tokens against a few hundred
Not a fit when
- The model already has a search you are happy with: ModSearch then only saves context
- You need to read an image or a screenshot: the author ships a separate skill, ModLens, for that
- The machine has neither Node 22 or newer, nor Bun, nor a ready `modsearch` binary and you cannot install them
- You need a full search results listing with page-by-page crawling: the skill returns a short digest per source
Example request
Find which Node.js line is in maintenance mode right now and give me source linksLimitations
- X search goes only through Grok Build and needs SuperGrok or X Premium. Without it an X question goes to a web engine and the entry in the answer gets the `degraded` status.
- Free quotas are limited: Firecrawl without a key gives 1000 credits a month, and Keenable without a key gives 1000 requests an hour per IP address, shared by everyone behind that address.
- Addresses of public pages go to the Firecrawl cloud when pages are read. The command `modsearch config set firecrawl.keylessFetch false` keeps reading local.
- The local fetcher does not run JavaScript: pages drawn by scripts return little text and the fetcher says so in `uncertainty`.
- A reply takes 10–30 seconds on agent-loop engines and 2–3 seconds on direct APIs. The author does not accept pull requests, only issues.
How to disable. Delete the modsearch skill folder from the agent's skills directory: `~/.claude/skills/` for Claude Code, `~/.codex/skills/` for Codex, `~/.agents/skills/` for Pi and OpenCode. In DeepSeek Harness remove the @liustack/modsearch plugin in the plugins section. Keys live in `~/.modsearch/config.json`, and you can delete the `~/.modsearch` folder by hand.
FAQ
Do I need a key or an account for web search through ModSearch?
No. By default Firecrawl works with 1000 free credits a month and Keenable with 1000 requests an hour per IP address, both without an account. Your own Tavily, Exa or Firecrawl keys add a personal quota on top.
How do I search X through ModSearch?
The command `modsearch -q "query" --source x` sends the question to Grok Build. It must be installed and signed in to an account with SuperGrok or X Premium. A query that mentions a tweet or X goes there on its own and only there, and `--source web,x` searches both.
How do I read a page from a link without a tool of my own?
The command `modsearch -u "address"` returns the page content and useful outbound links. Adding `-q "what to focus on"` gives the reading engine a hint about what to pick from the page.
What happens when one engine runs out of quota?
ModSearch moves it to the end of the queue and takes the next healthy one. `warnings` says which engine is paused and until when. `modsearch doctor` shows the state without spending quota, and `modsearch state clear` resets the pauses.
How do I install ModSearch in DeepSeek Harness?
With `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modsearch@5.10.9`. The native `web_search` in dsh then runs on the ModSearch engine chain and no DeepSeek key is needed for search.
How do I add my own Tavily or Exa key?
The command `modsearch config set tavily.apiKey` without a value asks for the key with hidden input, and it lands in `~/.modsearch/config.json` with 0600 permissions. The same keys can come from the `TAVILY_API_KEY` and `EXA_API_KEY` variables, and then nothing is written to disk.
Discussion
No questions or reviews yet.
Related
SkillsA web search skill with no MCP server: four command-line clients search the web and 16 vertical domains, in batches and with page extraction
Web Access
web-access
A web access skill that picks between search, page fetch and driving your own browser over CDP
A skill that routes a question to the right AI platform and, via browser automation, collects the answer from its native search
The Firecrawl command-line client with agent skills: web search, scraping, crawling, URL mapping and page interaction
open-webSearch
open-websearch
Web search with no API keys: an MCP server, a CLI and a local daemon. It works by parsing search engine pages so it may break
Yandex search API skill via Apify
claude-skill-yandex-search-api
An agent skill: the full Yandex SERP as JSON with no official API key, via the Apify Yandex Search Scraper actor
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| ModSearch (this entry) | no | 815 | ||
| open-webSearch | no | not required | 1,872 | an MCP server, CLI and daemon that searches by parsing search engine pages, with no chain of cloud engines and no X search |
| AnySearch Skill | yes | 6,747 | a web search skill with four command-line clients and 16 topic areas | |
| ModLens | no | 4,409 | a skill by the same author that reads images instead of searching the web |
README in short
The repository holds a table of engines with free quotas and ways to enable them, a step-by-step INSTALL.md written for the agent itself, and a docs folder covering troubleshooting, security and setup in Codex, Claude Code, OpenCode and Pi. Check scenarios in evals cover page reading, protection against requests to local addresses and the degraded X search. A changelog and a Chinese version are included. MIT license.
README badge
Original SKILL.md
--- name: modsearch description: "Plug-in web search, X (Twitter) search, and page fetch for models without native web access. Use whenever the task needs current information, external facts, source links, posts from X, or the content of a specific URL, and the active model/harness has no native search or fetch tool. Runs the modsearch CLI to return structured JSON evidence. Also use when the user asks how to install or configure modsearch, or wants to switch engines or add a key." compatibility: Requires network access and one of node 22+/npx, bun/bunx, or a preinstalled modsearch binary on PATH. allowed-tools: Bash --- # ModSearch — Search & Fetch Bridge Skill Use this skill when: - The user asks about anything after your knowledge cutoff (releases, news, prices, versions) - The answer needs source links or verifiable external facts - The user asks what people are saying on X or Twitter (推特, 推文, tweets, threads) - The user gives a URL to read and the harness has no fetch tool - The user asks how to configure modsearch, add a key, or change engines Do not use this skill for: - Analyzing images (that is `modlens`) - Questions your own knowledge answers reliably and time does not affect - Searching inside DeepSeek Harness (dsh, `DSH_SHELL=1`): there modsearch runs as a plugin behind the native `web_search`. If dsh still answers from its default provider, the plugin is missing: point the user to Step 0 of INSTALL.md ## Prerequisites Run every modsearch command through the launcher bundled with this skill. Replace `<skill-dir>` with the directory this SKILL.md lives in: ```bash bash <skill-dir>/scripts/run.sh -q "test" # macOS / Linux powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 -q "test" # Windows ``` The launcher finds a working way to run modsearch and forwards your arguments to it unchanged. It tries, in order: a compatible `modsearch` already on `PATH`, then `npx`, then `bunx`. If none of those exists it prints a JSON diagnosis to stderr and exits 78, with a `nextSteps` list for the user. Relay those steps instead of retrying. To see the full diagnosis, run `bash <skill-dir>/scripts/run.sh doctor --json` (on a machine that can launch the CLI it also chains modsearch's own engine/config `doctor`). Nothing else needs setting up first: modsearch works with no config file. Web search and page fetch run out of the box on Firecrawl's keyless free quota (no signup, no key), and a configured engine or API key takes precedence when present. ### If you cannot run the launcher script Some harnesses forbid running scripts. Reason through the same order by hand and run the first line that works (the pinned version is 5.10.9): 1. A `modsearch` on `PATH` whose major version is 5 and is at least 5.10.9: `modsearch <args>`. 2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modsearch@5.10.9 modsearch <args>`.