pi-free-web-search

Free, browser-aware web search and readable content extraction for Pi coding agent, without paid APIs.

---

Why this package exists

pi-web-access is excellent, but its search path depends on Perplexity/Gemini. pi-free-web-search is for teams that want:

• zero paid APIs
• browser-aware behavior for automation, while defaulting searches to Yahoo and failing over across engines when needed
• HTTP-first performance with browser fallback only when quality requires it
• a package that feels native in Pi (tools, commands, status line, TUI rendering)

---

What it provides

Capability	Name	Description
Tool	free_web_search	Natural-language web search with HTTP-first and browser fallback pipeline
Tool	free_fetch_content	Readable content extraction from a URL with browser fallback for JS-heavy pages
Command	/free-search-info	Shows detected browser, engine, mode, and executable
Command	/free-search-test <query>	End-to-end smoke test from inside Pi
Command	/free-search-debug <query>	Runs a real search and shows detailed debug logs/attempt metadata
Command	/free-search-status	Shows recent per-engine health, latency, failures, and cooldown state for the current session
Prompt	/pi-search <topic>	Short research template that steers the current session/model to use free_web_search and free_fetch_content
Skill	free-web-researcher	Guidance for robust research flow with these tools

---

Quick start

1) Install dependencies

bun install

2) Run checks

bun run check
bun run smoke

3) Install into Pi

pi install /absolute/path/to/pi-free-web-search

4) Use the prompt shortcut

/pi-search exact Bun documentation for test reporters
/pi-search study the Playwright locator docs and explain best practices

---

How the search pipeline works

1. Detect browser context for automation.
2. Choose the configured search engine, or Yahoo by default.
3. Build search URL for the active engine.
4. Run HTTP search first.
5. Re-rank and quality-check results.
6. Escalate to browser automation only if needed and allowed.
7. Merge/dedupe/rerank final results.
8. Optionally fetch top-result content with readable extraction.

---

Supported targets

Operating systems

• macOS
• Linux

Browsers / families

• Safari
• Chrome
• Brave
• Edge
• Chromium
• Firefox
• Dia Browser (best-effort via Chromium-family fallback)

Search engines

• Google
• Bing
• DuckDuckGo
• Brave Search
• Yahoo
• SearXNG (if configured)

---

Configuration

Create ~/.pi/free-web-search.json:

{
  "mode": "auto",
  "httpFirst": true,
  "browserFallbackThreshold": 0.55,
  "preferredEngine": "yahoo",
  "locale": "en-US",
  "language": "en"
}

Project-local override is also supported:

.pi/free-web-search.json

Configuration reference

Field	Type	Default	Notes
mode	auto | visible | headless | ask | disabled	auto	Global browser execution policy (ask prompts before browser automation in Pi UI)
preferredBrowser	browser family	detected	Force browser family
preferredEngine	search engine id	yahoo	Force search engine
locale	string	system locale	Locale/market hint for engines that support it (for example Bing mkt)
language	string	system language	Language hint for engines that support it (for example Yahoo/Google hl)
searchTemplateUrl	string	per engine	Custom search URL template
browserExecutablePath	string	auto-resolved	Explicit browser executable
chromiumProfilePath	string	auto	Chromium-family profile path
firefoxProfilePath	string	auto	Firefox profile path
searxngBaseUrl	string	unset	Base URL for SearXNG
httpFirst	boolean	true	Skip HTTP path when false
browserFallbackThreshold	number	0.55	Quality threshold for fallback
httpTimeoutMs	number	10000	Timeout for HTTP search/fetch
browserNavigationTimeoutMs	number	12000	Browser navigation timeout
browserResultWaitMs	number	700	Additional wait for dynamic result content
contentMinMarkdownLength	number	200	Minimum extraction size before browser fallback
includeContentMinScore	number	2	Skip low-relevance search results when includeContent=true
maxContentFetchConcurrency	number	2	Max parallel content fetches when includeContent=true
engineHealthCooldownMs	number	600000	How long session engine failures remain cooled down before retry
engineFailureThreshold	number	2	Consecutive failures before a session temporarily skips an engine
userAgent	string	bundled UA	Override request UA

---

Usage examples in Pi

free_web_search({ query: "Bun runtime documentation", numResults: 5 })
free_web_search({ query: "React server components caching", includeContent: true })
free_web_search({ query: "Supabase RLS docs", domainFilter: ["supabase.com"] })
free_web_search({ query: "OpenAI Responses API reference", engine: "yahoo", mode: "headless", debug: true })
free_fetch_content({ url: "https://bun.sh/docs" })

For manual diagnostics inside Pi:

/free-search-debug OpenAI Responses API documentation

---

Development

bun install
bun run typecheck
bun test
bun run check
bun run smoke

# CI-safe smoke mode (no browser automation)
FREE_WEB_SMOKE_MODE=disabled FREE_WEB_SMOKE_ALLOW_OFFLINE=1 bun run smoke

---

Open source project health

This repository includes the standard community health files and templates:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• SUPPORT.md
• Issue templates
• PR template
• Release configuration
• Changelog

---

Notes

• v0.x focuses on normal web pages, not YouTube/PDF/GitHub-specialized extraction flows.
• Browser and engine detection are best-effort and can be overridden in config.
• Safari automation uses Playwright WebKit instead of directly controlling Safari binaries.
• The package is authored and tested with Bun.

---

License

MIT — see LICENSE.