@graelo/pi-searxng

A minimalist SearXNG web search extension for Pi.

Source: github.com/graelo/pi-searxng

This is a focused, no-frills implementation that provides only web search and result caching — no content fetching, no repository cloning, no external services beyond a SearXNG instance.

Note: This is a fork of amartinr/pi-searxng (itself a fork of jcha0713/pi-searxng), maintained independently. Notable changes: configuration via @graelo/pi-ext-config with trusted-project support, removal of the get_search_result tool, and an improved in-memory cache.

Features

• Web Search - Search the web via a SearXNG instance
• Cached Results - Avoid redundant requests for identical queries
• Smart Caching - Freshness TTL, LRU eviction, and query deduplication
• Safesearch - Configurable content filtering (off, moderate, strict)

Design Philosophy

This extension follows a minimalist approach:

• Web search only — No content fetching, no HTML-to-Markdown conversion
• No repository cloning — Unlike the original, it doesn't clone GitHub repos
• No external tools — Doesn't require git or any system dependencies
• Self-contained — Everything runs in-process, no background services
• Updated imports — Uses current @earendil-works/ scoped packages (Pi coding agent, TUI, TypeBox)

If you need content extraction or repo browsing, consider using other Pi extensions for those tasks.

Installation

pi install npm:@graelo/pi-searxng

Or try without installing:

pi -e npm:@graelo/pi-searxng

Developing

npm install
npm run check
npm test

There is no build step — Pi loads src/index.ts directly, so npm run check (tsc --noEmit) type-checks without emitting anything.

Configuration

Create a config file at one of these locations (checked in order — the first one that exists is the only one read):

1. <repo-root>/.pi/extensions/pi-searxng/config.json — project-local, considered only after Pi has started a session and ctx.isProjectTrusted() is true. The repository root is found by walking up from the session directory to the nearest .git.
2. ~/.pi/agent/extensions/pi-searxng/config.json — global, always available, including for untrusted projects. Before session_start, the extension uses built-in defaults until a session-specific configuration can be resolved.

A project-local file replaces the global one entirely rather than overriding individual fields, so it should list every setting you want: anything it omits falls back to the built-in defaults, not to your global config.

{
  "searxngUrl": "http://localhost:8080",
  "timeoutMs": 30000,
  "maxResults": 10,
  "safesearch": "off",
  "engines": ["exa", "duckduckgo", "startpage", "mojeek", "wikipedia"]
}

Field	Type	Default	Description
searxngUrl	string	http://localhost:8080	URL of the SearXNG instance (can also be set via SEARXNG_URL env var)
timeoutMs	number	30000	HTTP request timeout in milliseconds
maxResults	number	10	Maximum number of results returned per search
safesearch	string	"off"	Content filtering level ("off", "moderate", "strict")
engines	string[]	[]	Engine names (not shortcuts) available on the SearXNG instance. Used to validate the engines parameter of web_search (see Engine selection). Never restricts searches by itself.

Or use an environment variable:

export SEARXNG_URL=http://localhost:8080

Tools

web_search

Search the web using SearXNG. Results are automatically cached for subsequent identical queries.

Parameters:

• query (string, required) - Search query
• limit (number, optional) - Max results to return (overrides maxResults from config). Note: the actual number returned depends on SearXNG's internal configuration.
• engines (string[], optional) - Restrict the search to specific engine names (e.g. ["duckduckgo", "wikipedia"]). Valid values are validated against the engines config key when it is set.

Returns: The matching search results. Identical queries (including the limit and engines parameters) are served from the in-memory cache while the cached entry is fresh.

Engine selection

SearXNG matches engines by name (as reported by the instance's /config endpoint), not by shortcut, and it silently ignores unknown names — a request for a non-existent engine searches all engines. The extension guards against this when the engines config key is set:

• All requested engines are in the list → the search is restricted to them.
• Some are unknown → the search runs on the valid subset, and the response starts with a note naming the ignored engines and the available ones.
• None are valid → the tool returns an error listing the available engines, and no search is performed. Without this, SearXNG would silently search every engine while the model believes it restricted the search.

Without an engines key in the config, requested engines are passed through to SearXNG unvalidated. The config list must be kept in sync with the instance's engine list manually — an engine listed in the config but not installed on the server behaves like the pass-through case above.

Error Handling

web_search returns error messages within the response content when something fails. If SearXNG is unreachable, the error includes the HTTP status and response body.

Empty result lists are often caused by upstream search engines being rate-limited or blocked rather than by the query itself. When SearXNG reports unresponsive engines, the response includes a note listing them (e.g. Note: 2 search engine(s) unresponsive: google, bing), so transient failures are distinguishable from genuinely no matches. If the search only produced answers or infoboxes (no web results), those are returned instead of a bare "No results found."

Result Format

Results are returned as numbered entries with the following structure:

1. **Result Title**
   https://example.com
   Short snippet of the result content...

Each result includes the title, URL, and a snippet (truncated to 200 characters).

When a search yields no web results but SearXNG found direct answers or infoboxes, those are returned instead:

Answer: 42

**Wikipedia — Douglas Adams**
   English writer and humorist...
   https://en.wikipedia.org/wiki/Douglas_Adams

Caching

The package includes an in-memory cache that reduces redundant calls to SearXNG:

• Query deduplication — Identical queries with the same limit and engine selection share a cache entry.
• Empty results are never cached — Empty result lists are often a transient upstream failure (engines rate-limited or blocked), so they always trigger a new search on the next call instead of being served from cache.
• Freshness TTL — Cache entries are considered fresh for a configurable period (default: 15 min). Stale entries trigger a new search instead of returning cached results.
• Eviction TTL — Entries that haven't been accessed within 24 hours are automatically removed.
• LRU eviction — When the cache exceeds 200 entries, the oldest (least recently used) entries are evicted.
• Lazy cleanup — Cleanup runs automatically at the start of each tool call.

Cache configuration

These fields can be added to either config location described above:

Field	Type	Default	Description
cacheFreshnessMs	number	900000 (15 min)	How long cache entries are considered fresh before re-searching
cacheTtlMs	number	86400000 (24 hours)	Max time an entry stays in cache without being accessed
cacheMaxSize	number	200	Max number of entries before LRU eviction kicks in

Requirements

• Node.js 24+
• A running SearXNG instance (for web search)

License

MIT