pi-bsearch

Brave Search API as a pi tool extension. Wraps @steimerbyte/bsearch-cli and exposes two modes to the LLM:

• mode="llm" (default) — pre-extracted LLM Context from Brave, optimized for AI/RAG pipelines.
• mode="web" — classic web search with links + descriptions.

Install

pi install npm:@steimerbyte/pi-bsearch
omp plugin install npm:@steimerbyte/pi-bsearch

@steimerbyte/bsearch-cli is declared as a dependency, so the bsearch CLI is fetched and installed alongside the extension automatically.

Configuration

Add a bsearch block to ~/.pi/agent/settings.json:

{
  "bsearch": {
    "apiKey": "BSA...",
    "defaultMode": "llm",
    "defaultMaxUrls": 20
  }
}

The API key is resolved in this order at every tool call:

1. settings.json → bsearch.apiKey (user-curated, wins)
2. process.env.BRAVE_API_KEY
3. ~/.bsearch-env (bsearch-cli's own env file — read for consistency)
4. Interactive prompt (persisted back to settings.json)

Get a key at https://api.search.brave.com/app/keys.

Compatibility

Built for @earendil-works/pi-coding-agent (upstream pi). omp (@oh-my-pi/pi-coding-agent v18.1.2) is supported via its legacy @earendil-works/* shim, so the same package is loaded through both hosts without declaring omp as a peer dependency.

Tool

The extension registers a single bsearch tool. Schema:

| Parameter | Type | Description | |---|---|---| | query | string (required) | Search query | | mode | "llm" | "web" | Search mode (default: llm) | | count | int 1–50 | Number of web results | | freshness | "pd" | "pw" | "pm" | "py" | Freshness filter | | max_tokens | int 1024–32768 | Max tokens in LLM context | | max_urls | int 1–50 | Max URLs in response | | threshold | "strict" | "balanced" | "lenient" | "disabled" | Relevance threshold | | safesearch | "off" | "moderate" | "strict" | SafeSearch (web mode) | | country | 2-letter code | Country code | | city | string | City name | | local | boolean | Force local/POI recall | | compact | boolean | Compact output | | timeout | int 1000–120000 | Request timeout in ms |

Output is truncated to 50 KB / 2000 lines (whichever comes first). When truncated, the full output is saved to a temp file and the path is appended to the result.

Slash command

/bsearch              Show current settings
/bsearch reload       Re-read settings.json from disk
/bsearch clear-key    Remove bsearch.apiKey from settings.json

Release

Bump version and publish:

npm version <patch|minor|major>
git push --follow-tags origin main

npm version updates package.json, creates a vX.Y.Z tag, and runs prepublishOnly (typecheck) before publishing. The publish workflow at .github/workflows/publish.yml triggers on v* tag push.

For a dry run before tagging: npm run release runs the typecheck.

Development

# Run with a local check-out
pi -e ./extensions/bsearch.ts

# Or install from a local path
pi install ./pi-bsearch

License

MIT