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

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

⚠️ bsearch-cli reads ~/.bsearch-env before process.env. If both paths exist, the env-file wins inside bsearch. To use a settings.json key, either remove ~/.bsearch-env or mirror the key there.

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

Development

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

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

License

MIT