How liustack/modsearch works
ModSearch adds web search, X search, and page fetching to coding-agent harnesses. A request enters through the CLI or the documented dsh plugin, is planned into engine roles and fallback order, then runs against configured providers; results and failures are returned as structured evidence. Configuration, key rotation, and quota cooldowns support that path, while local fetching adds HTML extraction and SSRF protections. The graph follows shown imports and calls plus README-documented capabilities; unsampled subsystem links are omitted where their wiring is not evidenced.
Main entry points: index.ts Engine registry · search.ts Search execution · config.ts Config and keys · main.ts ModSearch CLI
Components 28
Agent entrypoints
- ModSearch CLI
src/main.ts - dsh plugin
dsh/index.js
Request orchestration
- Role and fallback planner
src/router.ts - Search execution
src/search.ts - Output schema
src/schema.ts - CLI engine runner
src/subprocess.ts
Search and fetch engines
- Engine registry
src/providers/index.ts - Firecrawl provider
src/providers/firecrawl.ts - Keenable provider
src/providers/keenable.ts - You.com provider
src/providers/youcom.ts - Antigravity provider
src/providers/antigravity.ts - Tavily provider
src/providers/tavily.ts - Exa provider
src/providers/exa.ts - Grok X provider
src/providers/grok.ts - Local page fetch
src/providers/httpFetch.ts
Configuration and safeguards
- Config and keys
src/config.ts - Health diagnostics
src/doctor.ts - Quota cooldown
src/cooldown.ts - SSRF network guards
src/providers/http/network.ts - HTML text extraction
src/providers/http/htmlExtract.ts - Runtime environment
src/system.ts - Endpoint settings
src/providers/endpoint.ts - Provider limits
src/providers/limits.ts - API key parsing
src/util/apiKeys.ts - Proxy resolution
src/util/proxy.ts - Timed HTTP requests
src/util/timedRequest.ts - Secret redaction
src/util/redact.ts
Other components
- Agent user
Connections 47
- Agent user → ModSearch CLI: requests search
src/main.ts - Agent user → dsh plugin: uses plugin
README.md - dsh plugin → Search execution: runs engine chain
README.md - ModSearch CLI → Search execution: runs request
src/main.ts - ModSearch CLI → Config and keys: loads settings
src/main.ts - ModSearch CLI → Health diagnostics: runs diagnosis
src/main.ts - ModSearch CLI → Engine registry: lists engines
src/main.ts - Health diagnostics → Config and keys: checks settings
src/doctor.ts - Health diagnostics → Quota cooldown: checks cooldowns
src/doctor.ts - Health diagnostics → Engine registry: checks providers
src/doctor.ts - Search execution → Config and keys: loads settings
src/search.ts - Search execution → Role and fallback planner: plans run
src/search.ts - Search execution → Engine registry: selects engines
src/search.ts - Search execution → Quota cooldown: reads cooldown
src/search.ts - Search execution → CLI engine runner: runs commands
src/search.ts - Role and fallback planner → Config and keys: reads engine settings
src/router.ts - Role and fallback planner → Quota cooldown: reorders cooling engines
src/router.ts - Role and fallback planner → Engine registry: resolves providers
src/router.ts - Engine registry → Firecrawl provider: registers provider
src/providers/index.ts - Engine registry → Keenable provider: registers provider
src/providers/index.ts - Engine registry → You.com provider: registers provider
src/providers/index.ts - Engine registry → Antigravity provider: registers provider
src/providers/index.ts - Engine registry → Tavily provider: registers provider
src/providers/index.ts - Engine registry → Exa provider: registers provider
src/providers/index.ts - Engine registry → Grok X provider: registers provider
src/providers/index.ts - Engine registry → Local page fetch: registers provider
src/providers/index.ts - Local page fetch → SSRF network guards: validates targets
src/providers/httpFetch.ts - Local page fetch → HTML text extraction: extracts visible text
src/providers/httpFetch.ts - Local page fetch → Proxy resolution: resolves proxy
src/providers/httpFetch.ts - Firecrawl provider → Endpoint settings: resolves endpoint
src/providers/firecrawl.ts - Firecrawl provider → Provider limits: applies limits
src/providers/firecrawl.ts - Exa provider → Endpoint settings: resolves endpoint
src/providers/exa.ts - Tavily provider → Endpoint settings: resolves endpoint
src/providers/tavily.ts - Firecrawl provider → Timed HTTP requests: sends timed request
src/providers/firecrawl.ts - Exa provider → Timed HTTP requests: sends timed request
src/providers/exa.ts - Tavily provider → Timed HTTP requests: sends timed request
src/providers/tavily.ts - Timed HTTP requests → Proxy resolution: resolves proxy
src/util/timedRequest.ts - Timed HTTP requests → Secret redaction: scrubs errors
src/util/timedRequest.ts - Search execution → API key parsing: splits keys
src/search.ts - Search execution → Secret redaction: scrubs failures
src/search.ts - Config and keys → API key parsing: parses key values
src/config.ts - Config and keys → Secret redaction: masks credentials
src/config.ts - Quota cooldown → Config and keys: reads cooldown policy
src/cooldown.ts - Quota cooldown → Secret redaction: scrubs reasons
src/cooldown.ts - Search execution → Output schema: formats result
- Antigravity provider → Runtime environment: uses runtime context
src/providers/antigravity.ts - Grok X provider → Runtime environment: uses runtime context
src/providers/grok.ts