pi-searxng-search

Local SearXNG-backed web_search tool for pi.

This package only searches. It returns compact Google-style results with titles, URLs, and snippets.

Important: this package does not fetch or extract page contents. For a useful search workflow, install a separate fetch plugin too. pi-smart-fetch is recommended, but any plugin that provides web_fetch / batch_web_fetch can work.

Why this exists

Most web search tools for coding agents rely on an API key, hosted account, or vendor-specific search backend such as Brave, Google, or Ollama's account-backed web search.

pi-searxng-search is built for a different workflow:

• local-first search through your own SearXNG instance
• no API key
• no account signup
• no hosted search dependency
• simple search-only behavior
• clean pairing with whichever web_fetch plugin you prefer

The intended agent workflow is:

1. web_search discovers relevant URLs.
2. web_fetch or batch_web_fetch reads selected pages as a separate step.

Install

pi install npm:pi-searxng-search

Recommended companion fetch plugin:

pi install npm:pi-smart-fetch

Why fetch is separate: some users may already have another fetch plugin installed. Keeping fetch separate avoids duplicate web_fetch registrations and lets this package stay focused on local SearXNG search.

Local development install

pi install ~/github/pi-searxng-search

Or try it for one run:

pi -e ~/github/pi-searxng-search

Local SearXNG

A working local SearXNG compose setup is included in searxng/.

cd searxng
podman compose up -d
curl 'http://127.0.0.1:8080/search?q=searxng&format=json'

Docker Compose works too:

cd searxng
docker compose up -d

Official SearXNG docs:

• Container installation
• settings.yml
• Search API

JSON output must be enabled in SearXNG. The included config does this with:

search:
  formats:
    - html
    - json

Configuration

By default, the tool queries:

http://127.0.0.1:8080

If your SearXNG instance runs somewhere else, set SEARXNG_URL before starting pi:

export SEARXNG_URL='http://127.0.0.1:8888'
pi

Examples:

# Different local port
export SEARXNG_URL='http://127.0.0.1:8888'

# LAN or remote host
export SEARXNG_URL='http://192.168.1.50:8080'

# Reverse-proxied HTTPS instance
export SEARXNG_URL='https://search.example.com'

The tool also accepts a per-call base_url argument, but SEARXNG_URL is the recommended persistent configuration.

If you use the included compose setup and want to change its local port, copy .env.example to .env inside searxng/ and edit SEARXNG_PORT:

cd searxng
cp .env.example .env
$EDITOR .env
podman compose up -d

Example searxng/.env:

SEARXNG_PORT=8888
SEARXNG_BASE_URL=http://localhost:8888/

Then configure pi to match:

export SEARXNG_URL='http://127.0.0.1:8888'

Persist SEARXNG_URL

The export ... command above only affects the current terminal session. To make it stick, add it to your shell config.

For bash, add this to ~/.bashrc:

echo "export SEARXNG_URL='http://127.0.0.1:8888'" >> ~/.bashrc

Then restart your terminal, or run:

source ~/.bashrc

For zsh, add this to ~/.zshrc:

echo "export SEARXNG_URL='http://127.0.0.1:8888'" >> ~/.zshrc

Then restart your terminal, or run:

source ~/.zshrc

For fish, run:

set -Ux SEARXNG_URL 'http://127.0.0.1:8888'

Fish stores universal variables automatically, so you do not need to edit a config file.

Replace http://127.0.0.1:8888 with your actual SearXNG URL.

Tool

Registers:

• web_search

Parameters:

• query — search query
• max_results — maximum results to return, default 5, clamped to 1..50
• categories — optional comma-separated SearXNG categories
• engines — optional comma-separated SearXNG engines
• language — optional language code, for example en or auto
• time_range — optional day, month, or year
• safesearch — optional 0, 1, or 2
• page — optional page number, default 1
• base_url — optional SearXNG base URL
• timeout_ms — optional request timeout, default 15000

Default SearXNG URL resolution:

1. base_url tool argument
2. SEARXNG_URL environment variable
3. http://127.0.0.1:8080

Example result format:

Search results for: leptos server functions

1. Server Functions - book.leptos.dev
   URL: https://book.leptos.dev/server/25_server_functions.html
   Leptos is one of a number of modern frameworks that introduce...
   google · general

Development

npm install
npm run typecheck

License

MIT