pi-websearch

A pi extension that adds a WebSearch tool for searching the web via a configurable provider.

Providers

Two search backends are supported, configured via the provider option:

Provider	Description
exa-mcp	Exa MCP server over JSON-RPC HTTP (default)
searxng	Self-hosted SearXNG metasearch instance

Usage

Once installed, the LLM can call the WebSearch tool to search the web for current information, cite sources, and scrape specific URLs.

Tool parameters

Parameter	Type	Default	Description
query	string	(required)	Search query
numResults	number	8	Number of results to return
type	string	"auto"	Search type: "auto", "fast", or "deep"
livecrawl	string	"fallback"	Live crawl mode: "fallback" or "preferred"
contextMaxCharacters	number	10000	Max characters for LLM-optimized context

Configuration

Configuration is loaded from two JSON files (project overrides global, global overrides defaults):

Location	Purpose
~/.pi/agent/pi-websearch.json	Global config (applies to all projects)
<project>/.pi/pi-websearch.json	Project-level config (overrides global)

Options

{
  // Which provider to use: "exa-mcp" or "searxng" (default: "exa-mcp")
  "provider": "exa-mcp",

  "exaMcp": {
    // MCP server URL (default: "https://mcp.exa.ai/mcp")
    "url": "https://mcp.exa.ai/mcp",
    // MCP tool name (default: "web_search_exa")
    "tool": "web_search_exa"
  },

  "searxng": {
    // SearXNG instance URL (default: "http://localhost:8080")
    "url": "http://localhost:8080",
    // SafeSearch: 0 (off), 1 (moderate), 2 (strict)
    "safesearch": 0,
    // Optional path to a custom management script
    "script": "/path/to/custom-searxng"
  },

  // Request timeout in milliseconds (default: 25000)
  "timeoutMs": 25000,

  // Default values for search parameters
  "defaults": {
    "numResults": 8,
    "type": "auto",
    "livecrawl": "fallback",
    "contextMaxCharacters": 10000
  }
}

All keys are optional — missing keys fall back to built-in defaults.

SearXNG provider

When provider is set to "searxng", the extension manages a local SearXNG Docker instance automatically:

• On session_start, the extension starts SearXNG via docker compose up -d (using the bundled bin/searxng script or a custom script).
• On session_shutdown (quit), it stops SearXNG when no other pi instances are using it.
• Instance tracking uses PID-based lock files under ~/.pi/agent/searxng-instances/.

Setting up SearXNG

The bundled docker-compose.yml and .env files are in searxng/. By default SearXNG listens on http://localhost:8080. You can change the port in searxng/.env (SEARXNG_PORT).

To use a custom management script, set searxng.script to a path (supports ~ expansion). The script must accept up and down commands — matching the interface of the built-in bin/searxng script.

Development

# Run tests from the workspace root
cd ../.. && pnpm run test

# Test locally with pi (from this package directory)
pi -e ./index.ts