@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"
}

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.

Returns: The matching search results. Identical queries are served from the in-memory cache while the cached entry is fresh.

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.

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).

Caching

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

• Query deduplication — Identical queries with the same limit share a cache entry.
• 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:

Requirements

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

License

MIT