SearchBoost

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 v0.2.0 branch unifies the formerly standalone pi-search-boost and dsh-search-boost projects into a single codebase under lib/. Documented commands specifying @latest retrieve the official published npm package. To explore or test the latest branch code, please follow Installation from Source & Development.

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 Evidence Loop (Experimental)
  • Engine Pools & Scoring Presets
• Parallel Multi-Agent Research Workflows
• Configuration, Security & Privacy
• CLI Command Reference (Headless & CI)
• Installation from Source & Development
• 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) and a high-tier API pool (Tavily, Brave, Exa). Automatically performs cross-engine URL deduplication, domain routing, and relevance re-ranking.
• Clean Webpage Content Extractor (fetch_page)
  Uses Jina Reader by default for clean markdown extraction, backed by a guarded local HTML reader fallback. 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. Recovers accurate UTC timestamps from Snowflake post IDs and enforces local author/date filtering without hallucination.
• Jev Adaptive Evidence Loop (adaptive_search · Experimental)
  Connects with TypeSafe Jev to orchestrate multi-step search loops and evaluate evidence fragments across 1–6 targeted questions. Operates under strict token/step budgets and returns deterministic coverage states (covered, insufficient, unassessed, not_searched, failed).
• 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 encrypted in local private configs (POSIX 0600). Enforces local SSRF protection, target IP address pinning, and proxy compliance, with zero credential leakage into model prompts.

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 · updates
                              │
                    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.

Supported Hosts Matrix

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 robust free engine pool (Bing, DuckDuckGo, Yahoo, Exa-free). You can begin searching immediately without signing up for any paid provider!

2. 3-Step Setup Wizard

1. Select Setup in the TUI menu. 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: Upgrading via TUI

Whether you run unified search-boost or have legacy pi-search-boost / dsh-search-boost installations, select Update in the TUI to upgrade everything:

# Option 1: Open the interactive menu
search-boost
# -> Select "Update"

# Option 2: Run headless update
search-boost upgrade -y

Update Behavior: Fetches the latest published release, updates SearchBoost, and refreshes prompt assets across all configured agents while preserving existing keys, layer choices, and permission settings.

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:

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

# Once migrated, routine updates only require:
search-boost
# -> Select "Update" (or search-boost upgrade -y)

Interactive Console (TUI)

Launch search-boost without arguments to access the interactive dashboard built with Clack. Manage installation, updates, and credentials effortlessly:

Tool Suite & Usage Guide

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

Tool Responsibilities & Boundaries

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), api (configured paid engines only), or hybrid (all available engines).
• ranking: Scoring presets: balanced (default), research (favors authoritative/documentation sources), or fresh (favors recent publications).
• 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. Prioritizes Jina Reader for clean Markdown, with an internal guarded HTTP fetcher fallback.

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.

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:

{
  "query": "Claude 3.7 Sonnet hybrid reasoning from:AnthropicAI",
  "mode": "keyword",
  "max_results": 5
}

• Precise Timestamps: When platform timestamps are missing or inconsistent, recovers true UTC creation times from 64-bit Snowflake IDs.
• Native Operators: Full support for from:username, since:YYYY-MM-DD, and until:YYYY-MM-DD.

4. adaptive_search Jev Evidence Loop (Experimental)

When rigorous verification is required for complex technical claims, agents can call adaptive_search. The Jev cognitive loop formulates targeted queries, selects allowable engines, fetches relevant passages, and assesses coverage.

Tool Arguments Example:

{
  "questions": [
    "What cancellation guarantees does the official documentation provide for this API?",
    "In which stable release was this behavior originally introduced?"
  ]
}

• Accepts 1–6 non-empty questions, each up to 400 characters.
• Returns per-question coverage status:
  • covered: Assessed fragments satisfy the question's criteria (model judgment).
  • insufficient: Retrieved material does not fully answer the claim.
  • unassessed: Intermediate state or evaluation not completed.
  • not_searched: Query budget or deadline exhausted before execution.
  • failed: An error occurred during retrieval or parsing.

Engine Pools & Scoring Presets

In fused_search, base weights are governed by engine_pool and ranking:

Parallel Multi-Agent Research Workflows

Installing SearchBoost into an MCP host automatically installs two bundled skills:

1. search-boost: Research routing skill guiding the agent to select optimal tools for open-ended questions.
2. search-boost-parallel-research: Multi-agent parallel workflow delegating independent research tracks to host subagents:

                           [ Parent Agent ]
                     Deconstructs Research Goals
                                   │
                 ┌─────────────────┴─────────────────┐
                 ▼                                   ▼
        [ Searcher Agent A ]               [ Searcher Agent B ]
     Gathers Evidence via Tools         Gathers Evidence via Tools
                 │                                   │
                 └─────────────────┬─────────────────┘
                                   ▼
                         [ Summarizer Agent ]
                      No Tools · Pure Synthesis
                                   │
                                   ▼
                       [ Final Parent Report ]

• Two Workflow Modes:
  • Fast Mode: Single concurrent wave (1 Wave) followed immediately by parent synthesis.
  • Complex Mode: Adds a "Gap Review" step, launching a second wave only if critical information is missing.
• Graceful Degradation: If the host lacks subagent capabilities, the workflow gracefully falls back to serial deep research without infinite loops.

Configuration, Security & Privacy

Configuration Layout

Local configuration is stored in ~/.search-boost/config/ (configurable via SEARCH_BOOST_HOME):

~/.search-boost/
├── config/
│   ├── keys.json        # Search engine API keys & Jev credentials (mode 0600)
│   ├── layer.json       # Search layer compatibility mode (free / api)
│   └── xauth.json       # X (Twitter) authentication tokens
├── backups/             # Automatic configuration backups
└── state/               # Upgrade receipts and package tracking

Security & Privacy Guarantees

• Private File Permissions: On POSIX systems, configuration files are written atomically with strict 0600 permissions (read/write by owner only).
• SSRF Protection & IP Pinning: The direct HTML reader resolves and validates target IP addresses against private/loopback CIDRs, pinning the connection to prevent DNS rebinding attacks.
• Proxy Support: Fully respects HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY. Explicitly rejects SOCKS proxies with clear error messages to prevent accidental direct network leaks.
• TUN Fake-IP Compatibility: When operating behind a TUN interface utilizing Fake-IP ranges, set SEARCH_BOOST_TRUSTED_TUN=1 to allow trusted gateway routing.

CLI Command Reference (Headless & CI)

In addition to the interactive TUI, SearchBoost provides a comprehensive CLI for scripting and automation:

# ----------------- Core & Interactive -----------------
search-boost                                # Launch interactive dashboard (TUI)
search-boost status                         # Print active configuration and host summary
search-boost --help                         # Display full CLI documentation

# ----------------- Headless Installation -----------------
search-boost install -t cursor -y           # Install for Cursor with auto-approval
search-boost install -t claude,codex --keep-native  # Install while preserving host native search
search-boost install -t antigravity --workspace /path/to/project # Target a specific workspace
search-boost install -t pi -y               # Mount Pi extension and prompt templates
search-boost install -t dsh --profile web   # Connect to DeepSeek Harness web profile
search-boost install -t cursor --dry-run    # Preview installation without writing files

# ----------------- Configuration Management -----------------
search-boost config keys                    # Manage API keys from CLI
search-boost config layer                   # Switch default layer (free / api)
search-boost config x --import-grok         # Import X credentials from local Grok login
search-boost config jev                     # Configure Jev endpoint and token

# ----------------- Diagnostics & Health -----------------
search-boost doctor                         # Run offline diagnostic checks
search-boost doctor --strict                # Strict mode (exits non-zero on warnings)
search-boost doctor --json                  # Output machine-readable JSON report

# ----------------- Uninstall -----------------
search-boost uninstall -t cursor,claude -y  # Remove integrations from selected hosts

Installation from Source & Development

To contribute to SearchBoost or test the latest unreleased changes on the v0.2.0 branch:

Source Setup

# 1. Clone repository
git clone https://github.com/Mr-remon219/search-boost.git
cd search-boost

# 2. Switch to v0.2.0 branch and install dependencies
git switch v0.2.0
npm ci

# 3. Synchronize Grok plugin assets
npm run plugin:sync-grok

# 4. Link globally
npm install -g .

# 5. Launch and test
search-boost

Development Test Gates

Before submitting a PR, verify your changes against the complete test suite:

npm run prepublishOnly    # Syntax check + asset sync + full offline test suite
npm run test:network      # DNS, proxy, IP pinning, and security regressions
npm run test:adaptive     # Jev adaptive search loop evaluation
npm run test:adapters     # MCP, Pi, and DSH adapter protocol suites
npm run smoke             # MCP JSON-RPC protocol smoke test

License

This project is licensed under the MIT License.