@ikuma.cloud/pix-websearch

A native Pi Coding Agent websearch tool backed by Exa, Parallel, Firecrawl, Tavily, and TinyFish. Keyless access works without account setup; optional API keys use the corresponding provider account's limits.

Contributors must read CONTRIBUTING.md before making changes.

Run locally

From the repository root, follow the workspace setup, then:

mise run websearch:dev

Ask Pi to search for something, for example:

Search for the latest TypeScript release and summarize the changes with sources.

To load this package in an existing Pi installation, use its absolute path:

pi -e /absolute/path/to/pix/packages/websearch

Pi loads the package's TypeScript source directly; no build step is needed.

Configuration

PIX_WEBSEARCH_PROVIDER defaults to auto. Set it to exa, parallel, firecrawl, tavily, or tinyfish to select a fixed provider:

PIX_WEBSEARCH_PROVIDER=tavily mise run websearch:dev

Optional credentials are read when Pi loads the extension:

Keys are sent only in request headers. An empty key selects keyless access. Tavily uses X-Tavily-Access-Mode: keyless; TinyFish uses X-TinyFish-Access-Mode: keyless. Requests identify this package as pix-websearch, not OpenCode.

Keyless services are rate limited. TinyFish's keyless header is used by OpenCode v2 and was verified live on September 23, 2026, but is not described in TinyFish's public MCP guide at that date.

Automatic selection

auto randomly selects an available provider and keeps it for the Pi session. HTTP 429 puts that provider in cooldown and retries another provider. Each provider is attempted at most once per call. Retry-After seconds and HTTP dates are supported; missing or invalid values use 60 seconds.

Cooldowns live in memory in this extension instance and apply across sessions in the same Pi process. Session start/shutdown clears the remembered selection; reloading the extension clears all state. Separate Pi processes do not share cooldowns. If all providers are cooling down, the call fails immediately.

Fixed-provider mode reports errors directly. Automatic mode also reports authentication, network, parsing, and other non-429 failures directly.

Tool contract

websearch({ query: string })

• Queries must contain 1–4,000 characters after trimming.
• Up to eight results include URLs, titles, excerpts, and publication dates when available. Providers differ in coverage and excerpt depth.
• Model-facing output is Markdown, capped at 24 KiB with excerpts capped at 2,000 UTF-8 bytes each. Shortened output points to the source URLs.
• Pi tool-result details retains the provider and the normalized results.
• Every request has a 25-second timeout and a 256 KiB response limit. A call may try up to five providers after rate limits. Pi cancellation stops further work.
• The tool works in interactive and headless modes.

Development

mise run test --project pix-websearch
mise run check

Tests mock HTTP and isolate Pi discovery from personal configuration. They cover provider request/response contracts, JSON and SSE handling, bounded response reads, cancellation, rate-limit fallback, output limits, and Pi package loading.

Implementation references

The endpoint contracts and selection behavior were researched from OpenCode v2 at 1746672 and the provider documentation: Exa, Parallel, Firecrawl, Tavily, and TinyFish.

The MCP adapters make endpoint-specific tools/call POSTs and accept JSON or SSE. These endpoints accept calls without initialization; this transport is not a general-purpose MCP client. The implementation uses native fetch and no search provider SDKs.