pi-web-research

Web search and page extraction tools for Pi.

Why I built this

I used Claude's web research when I needed context on a topic. Questions like "best onboarding practices for iOS apps" or "how do I set up Swift Testing with async support" — I'd get sources back, then pull the relevant pieces into a dev plan or notes.

When I started using Pi for daily coding, that capability was missing. I didn't want to copy-paste search results into chat. I wanted the agent to handle the research: run parallel searches, evaluate what it finds, scope to authoritative domains when needed, and surface only what matters.

This extension adds web_search and web_fetch to Pi, along with a prompt template that guides that workflow.

Other tools I tried had too much overhead — complex configs, nested skills, features I never used. I just needed web research to work.

Tools

| Tool | Purpose | |------|---------| | web_search | Search the web via Brave Search API and return ranked results | | web_fetch | Fetch a URL, strip HTML, and extract content relevant to a specific prompt |

Examples

Research a specific technical topic:

"How do I migrate from XCTest to Swift Testing?"

Pi runs parallel searches, fetches the most relevant guide, and returns a summary with key steps and source links.

Check current best practices:

"What are the recommended error handling patterns for Swift concurrency?"

Useful when documentation is scattered across blog posts, WWDC videos, and release notes.

Evaluate a library before adoption:

"Is SwiftData production-ready? What are people saying about it in production apps?"

Pi searches for recent experience reports, fetches a few, and surfaces common issues and workarounds.

Install

Install from npm (simplest):

pi install @bcuev/pi-web-research

Or install directly from GitHub:

pi install git:github.com/bcuev/pi-web-research

Or clone and install locally:

git clone https://github.com/bcuev/pi-web-research.git
cd pi-web-research
pi install .

Setup

Sign up for a Brave Search API key, then export it in your shell:

export BRAVE_API_KEY=<your-key>

Features

• Search via Brave API — rate-limit errors include retry-after headers
• Caching — 15-minute TTL on raw and extracted content so you don't re-fetch the same page in a session
• Content-type guards — only extracts from text/*, JSON, XML, and XHTML; rejects binary or unknown types
• HTTPS → HTTP redirect guard — blocks cross-origin downgrades before reading the response body
• Truncation — truncates large results to fit context limits using Pi's built-in truncateHead
• Timeouts — 30-second network timeouts via AbortSignal; respects Pi's cancellation

Prompt template

The research.md prompt template tells Pi to:

1. Run 2 parallel broad searches
2. Evaluate quality before falling back to domain-scoped searches
3. Summarize findings with citations

Requirements

• Pi ≥ 0.70.0
• Node.js ≥ 20
• BRAVE_API_KEY environment variable

License

MIT