search-boost

Multi-engine web search & evidence synthesis for AI coding agents One shared core runtime, deeply adapted for MCP, Pi, and DeepSeek Harness

English · 中文文档

[!NOTE]

Release & Branch Notice: The formerly standalone pi-search-boost and dsh-search-boost projects are merged into one codebase under lib/. Documented commands specifying @latest retrieve the official published npm package. To test code that is not in a published release, check out the branch or tag you need and follow Installation from Source & Development.

v0.2.4: single-snapshot Jev screening (schema V5), private research save/recovery, bounded PDF text extraction, Desktop integration, and separate package updates / integration management. See the release and migration notes: V3 adaptive inputs/outputs and the upgrade command have changed. This source version does not imply npm publication; @latest follows the published registry.

Table of Contents

• Key Features
• System Architecture
• Supported Hosts Matrix
• Quick Start (30 Seconds)
• Upgrade & Migration Guide
• Interactive Console (TUI)
• Tool Suite & Usage Guide
• Tool Responsibilities & Boundaries
• 1. fused_search Multi-Engine Search
• 2. fetch_page Smart Content Reader
• 3. x_search X (Twitter) Intelligence
• 4. adaptive_search Jev Intent-Guided Search (Experimental)
• Engine Pools & Scoring Presets
• Parallel Multi-Agent Research Workflows
• Security
• CLI Command Reference (Headless & CI)
• Installation from Source & Development
• Friendly Links
• License

Key Features

• Multi-Engine Parallel Fusion (`fused_search`)

Queries multiple search providers in parallel. Features an out-of-the-box keyless free pool (Bing, DuckDuckGo, Yahoo, Exa-free, AnySearch) and a keyed API pool (Tavily, Brave, Exa, AnySearch). Automatically performs cross-engine URL deduplication, domain routing, and relevance re-ranking.

• Clean Webpage Content Extractor (`fetch_page`)

Fetches the origin first for low latency, with optional same-route curl compatibility fallback and Jina Reader backup. Strips CSS, JS, and ad clutter. Supports focused contextual paragraph extraction via focus, backed by in-memory caching and size limits.

• X / Twitter Community Intelligence (`x_search`)

Retrieves public posts, user timelines, and discussion threads via official xAI API or an anonymous fallback channel. Derives UTC timestamps from verifiable Snowflake post IDs and applies author/date filters only when metadata can be verified. Coverage may be incomplete, stale or empty; a retrieved sample does not establish platform-wide sentiment.

• Jev Intent-Guided Search (`adaptive_search` · Experimental)

Supply one full question and a required research intent. One pre-search Jev strategy request selects the fixed ranking preset and (when community is omitted) whether to add the already-wired community branch; one bounded fused snapshot (32 candidates for targets up to 10; larger targets keep the same headroom ratio, at most 160) is then screened with fixed safety, prototype value 3/4/5 and source-discount options. No keyword planning, no constraints gate, no language check, no automatic page read, and no self-set cumulative budget stop; cursor and saved-result pagination only replay stored results. No claim of verified or complete answers.

• Native Multi-Agent Parallel Research

Bundles search-boost and search-boost-parallel-research skills. In hosts supporting subagents (Cursor, Claude Code, Pi, DSH), tasks can be dispatched to parallel Searchers (gathering evidence) and Summarizers (pure synthesis without tools), supporting both Fast and Complex waves.

• Unified Core Across All Host Ecosystems

A single, host-neutral core runtime powering standard Model Context Protocol (MCP) servers, alongside native extensions for Pi and Cordis plugin bundles for DeepSeek Harness (DSH).

• Zero-Config Onboarding & Strict Security

Requires zero API keys to start using the free engine pool. Sensitive credentials are stored as plaintext in local private configs with restricted file permissions (POSIX 0600); this is not encryption at rest. Uses local networking and proxy DNS, with bounded requests and explicit fallback. Configured credentials are kept out of model prompts and diagnostic output.

System Architecture

SearchBoost follows a "One Core, Three Adapters" architecture. All search logic, content parsing, deduplication algorithms, and network safety mechanisms reside in the shared core:

SearchBoost TUI / CLI
             installation · configuration · refresh
                              │
                    Shared SearchBoost Core
                    lib/runtime.mjs facade
              search · fetch · X · adaptive evidence
                              │
              ┌───────────────┼───────────────┐
              │               │               │
         MCP Adapter      Pi Adapter     DSH Adapter
         stdio server     extension      Cordis bundle
              │               │               │
     ┌────────┴────────┐      ▼               ▼
     │ Cursor / Claude │      Pi       DeepSeek Harness
     │ Codex / Grok    │
     │ Antigravity     │
     └─────────────────┘

• Core (`lib/`): Host-neutral algorithms, engine orchestration, Jev client protocol, and network safety policies.
• Adapters (`adapters/`): Maps core operations into host-specific protocols (MCP JSON-RPC, Pi Extension API, DSH Cordis lifecycle).
• Agents (`agents/`): Host prompt contracts, workflow templates, and native skill definitions. See the prompt responsibility contract and beta.8 release notes for the Agent-facing routing update.

Supported Hosts Matrix

Host · Integration Type · Files / Mechanism · Capabilities & Notes Cursor / Cursor CLI · MCP + Skills · ~/.cursor/mcp.json / skills/ · Supports CLI auto-approval (cli-config.json), session start injection, parallel research skill Claude Code · MCP + Prompts · Official claude MCP config · Full multi-engine search and page extraction tools with prompt boundaries Codex · MCP + Prompts · Host MCP configuration · Seamless access to fused search, X retrieval, and reader tools Grok Build · MCP + Plugin · MCP config + bundled plugin · Automatically syncs and installs companion plugin when grok CLI is available Google Antigravity · MCP + Workspace · Workspace MCP configuration · Per-project workspace guidance and full search tool suite Pi · Native Extension · ~/.pi/agent/extensions/ / prompts/ · Registers native extension, /fast-parallel, /complex-parallel, searcher/summarizer roles DeepSeek Harness · Native Bundle · cordis.patch.yml / dsh plugin · Integrated with Cordis runtime; provides native research_parallel subagents and call cards

Quick Start (30 Seconds)

Prerequisites

• Node.js: >= 22.13.0
• Package Manager: npm (or pnpm)

1. Install & Launch the Dashboard

# Install globally
npm install -g search-boost

# Launch the interactive terminal UI (TUI)
search-boost

[!TIP]

Zero API Keys Required to Start: SearchBoost includes a keyless free pool (Bing, DuckDuckGo, Yahoo, Exa-free, AnySearch). No paid-provider signup is required; availability and result coverage depend on the providers and your network.

2. 3-Step Setup Wizard

1. Select Setup wizard on the default flat TUI home (folder layout: Installation & integrations → Setup). Configure engine keys (or skip to use free tier) and optional X credentials.
2. Check the agents you want to integrate (Cursor, Claude Code, Pi, etc.), confirming auto-approval and native search replacement.
3. Restart or reload your chosen agents, then ask them to research anything in conversation!

Upgrade & Migration Guide

1. Routine Updates: npm First, Then Refresh Integrations

The commands below describe v0.2.4. Before it is published, @latest may still install an older release without refresh or research; use a v0.2.4 source checkout as described below. Use npm to update the package; the TUI no longer updates SearchBoost itself. Installation, refresh and removal live under Manage agent integrations (folder layout: Installation & integrations → Manage agent integrations).

npm install -g search-boost@latest --prefer-online
search-boost
# → Manage agent integrations → Refresh existing integrations → select scopes
# Or refresh all existing integrations:
search-boost refresh -y
# Preview only:
search-boost refresh --dry-run

Refresh uses the current package and preserves credentials, permissions, disabled states and unrelated configuration. It does not install unconfigured hosts. Unchecking a target means no operation, not removal. The old upgrade command and --sync-only option are removed.

If a Grok local cache remains stale after native update, fully quit Grok and separately approve data-retaining reconstruction and trust of the displayed source. -y alone is not approval; explicit CLI approval is search-boost refresh -y --repair-grok-cache. This requests native uninstall --keep-data, then install --trust; legacy-name data reuse is not guaranteed. Restart affected hosts afterward. See integration refresh.

2. Migrating from Legacy search-boost-mcp

[!IMPORTANT]

If you have the old global package search-boost-mcp installed, npm cannot automatically replace the global binary across package renames. Use the one-line npx migration command. The refresh step below requires v0.2.4 or later:

# Execute safe migration via npx
npx --yes --package=search-boost@latest -- search-boost migrate -y

# For v0.2.4 and later, update the package before refreshing integrations:
npm install -g search-boost@latest --prefer-online
search-boost
# -> Manage agent integrations → Refresh existing integrations (or search-boost refresh -y)

Interactive Console (TUI)

Launch search-boost without arguments to access the interactive dashboard built with Clack. Manage host integrations, search configuration and credentials here; package updates are handled by npm:

The default flat home lists these actions in order:

Home entries · Behavior Setup wizard; Manage agent integrations; Status · Guided setup; install / scoped refresh / confirmed uninstall; read-only status Search engine configuration; Default search layer; Tool switches · Choose individual engines; free / api; shared MCP / Pi / DSH switches X credentials; Jev configuration (experimental) · Masked credential management Native web search; Print MCP snippet · Explicit permission choices; read-only snippets TUI settings; Exit · Menu layout before display language; close the console

TUI settings → Menu layout offers flat / folder. Folder mode retains Installation & integrations, Search & tools, Services & credentials and Status. Completed actions return to the same flat home entry or their folder submenu. Escape cancels/navigates back; Ctrl+C exits. A layout switch immediately returns to the new home. Management returns to its own submenu; interactive uninstall and Grok cache reconstruction default to cancel. Partial failures are reported, not styled as success.

Layout and language changes apply immediately and are saved in ~/.search-boost/config/tui.json (or $SEARCH_BOOST_HOME/config/tui.json). Missing layout (including legacy language-only settings) defaults to flat. Without a saved language preference, Chinese system locales select Simplified Chinese; other locales select English. The preference also applies to standalone interactive setup/config commands, not non-interactive CLI output, search results or agent replies. Tool names, commands, paths, MCP snippets and raw upstream errors remain unchanged. Dry-run previews layout/language without saving; malformed settings are warned about, not overwritten. See TUI navigation and language settings.

Tool switches

Open Tool switches (folder layout: Search & tools → Tool switches), toggle with Space, press Enter to review, then confirm. Esc or declining confirmation writes nothing; an empty selection disables all tools. Locked adaptive_search appears struck through in the status panel and is excluded from selectable choices until Jev is configured. Configuring Jev makes it available by default; an explicit OFF preference is preserved.

Preferences are shared through ~/.search-boost/config/tools.json (or $SEARCH_BOOST_HOME/config/tools.json), using atomic, locked writes. No host restart or reinstall is needed once the updated adapters are loaded:

• MCP: tool-list updates within approximately 300ms, with tools/list_changed notification; clients ignoring notifications may need reconnecting.
• Pi: active tools refresh within approximately 300ms; unrelated and initially excluded tools are preserved. Watchers stop on session shutdown.
• DSH: registrations remain present but disabled calls fail immediately; the native search/fetch provider paths obey the same switches.

Every new invocation checks the current preference, including stale tool handles. Existing requests finish normally. Removing Jev credentials locks adaptive calls (including pagination and saved-result recovery); restoring credentials does not override explicit OFF. These are tool-entry switches, not engine permissions: enabled adaptive research screens one internal fused snapshot and does not read pages automatically, and fused community search may still use internal X retrieval. Searcher waves in Pi/DSH also require the shared fused_search and fetch_page entries and DSH scoped tools: disabled dependencies prevent initial dispatch, and are checked again before each child starts. Started children finish normally; tool-free summarizers do not require these entries. Checks never enable tools or expand permissions. Slash commands remain available for recovery. Existing processes running older adapter code require one reload/update first. Hosts sharing these settings must use the same SearchBoost home.

Tool Suite & Usage Guide

When integrated, agents automatically receive standard tool definitions and autonomously determine when to call them.

Tool Responsibilities & Boundaries

Tool · Best Used For · Boundary / Non-Goals fused_search · Parallel multi-engine querying, deduplication, and diversity re-ranking · A single search step; follow-up decisions remain with the parent agent fetch_page · Reading clean content from public URLs with optional keyword focus · Not an authenticated browser; local network and proxy policy still apply x_search · Retrieving public X posts, author timelines, or discussion threads · Does not guarantee exhaustive comment threads or total sentiment sampling adaptive_search · Experimental: one bounded fused snapshot + fixed-option Jev screening for one question and a required intent · Selected URLs with reviewed extracts and value labels; targetMet is quantity only, not verified answers search_stats · Reading engine status, memory cache hits, and recent diagnostic stats · Read-only; configuration readiness does not guarantee active external network reachability search_layer · Viewing or switching compatibility search layer in MCP · show is read-only; changing layers mutates persistent configuration on disk

1. fused_search Multi-Engine Search

Dispatches queries across engines concurrently, normalizes URLs, strips redirects, and applies diversity filters.

Tool Arguments Example (JSON):

{
  "query": "Node.js 22 built-in WebSocket API guide",
  "include_domains": ["nodejs.org", "developer.mozilla.org"],
  "engine_pool": "free",
  "ranking": "balanced",
  "complexity": "simple",
  "max_results": 5
}

• `engine_pool`: free (keyless Bing, DuckDuckGo, Yahoo, Exa-free, AnySearch), api (configured API engines), or hybrid (both pools). Unavailable or disabled engines are skipped. When omitted, the compatibility layer maps free to the free pool and api to hybrid.
• `ranking`: Final engine-weight presets: balanced (default), research, or fresh. They do not change query variants, search depth or recency filters, and do not establish source authority or freshness.
• `complexity`: simple (1 query variant), medium (up to 2 variants), complex (up to 3 deep variants).
• `community`: Boolean (false by default). Set to true to blend real-time X developer discussions into the final result quota.

2. fetch_page Smart Content Reader

Reads webpage content from search URLs. Reads and cleans the origin first; PDFs are extracted to text locally and only fall back to Jina Reader when that fails; curl handles transport compatibility when installed.

Tool Arguments Example:

{
  "url": "https://nodejs.org/api/globals.html",
  "focus": "AbortSignal.any"
}

• `focus` (Optional): Filters and retains paragraphs matching the target keywords.

[!TIP]

A focus miss does not prove the information is absent from the page. If in doubt, re-fetch without focus to inspect the full context.

• `offset` (Optional): Long bodies are returned in bounded windows (60,000 characters by default). The result reports totalChars and, while more content follows, nextOffset; pass that back as offset to continue reading. Continuations are served from the 24h cache without another request.

[!TIP]

Binary responses (images, archives, PDFs with no extractable text) raise a clear error instead of being returned as page text.

3. x_search X (Twitter) Intelligence

Designed for real-time technical tracking and first-party developer updates. Supports keyword search, author timelines, and thread conversations.

Tool Arguments Example: