Skip to the page
Get started free

pi-websearch

Point pi-websearch's tavily backend at SpecStream with one websearch.json file, and the pi agent's web_search tool answers from the SpecStream Search API at $1 per 1,000 searches of up to 10 results.

SpecStream for pi-websearchCoding agents

What you need

  • The pi coding agent.
  • A SpecStream API key. New accounts start with $10 of credit, no card. Get your key on the Search API screen of your SpecStream workspace.

  1. 1. Install pi-websearch

    pi-websearch is not on npm, so install it from its repository. Pi clones it and loads its web_search tool:

    Terminal
    pi install git:github.com/code-yeongyu/pi-websearch

  2. 2. Write websearch.json

    pi-websearch reads the first of .pi/websearch.json in the current project, ~/websearch.json and ~/.pi/websearch.json. Put the file in your home folder so the key stays out of project repositories, and put your key in place of YOUR_SPECSTREAM_API_KEY:

    baseUrl is the whole search address, with /search at the end. pi-websearch posts to baseUrl exactly as written and adds no path, so https://api.specstream.ai/tavily alone would miss the search route.

    "auto": false makes SpecStream the only route. With auto on, the default, pi-websearch first tries the search tool built into models that have one (Claude, GPT 5, Grok and others), and SpecStream answers only when that fails.

    ~/.pi/websearch.json
    {
      "backend": "tavily",
      "apiKey": "YOUR_SPECSTREAM_API_KEY",
      "baseUrl": "https://api.specstream.ai/tavily/search",
      "maxResults": 10,
      "auto": false
    }

  3. 3. Check it in pi

    Start pi and run /websearch status to see its activation state. Then ask about something from this week. The search line in the TUI names tavily as the provider, and the results carry the title, URL and text of each page SpecStream found.

What SpecStream answers

https://api.specstream.ai/tavily/search takes Tavily's request and answers in Tavily's shape: results with title, url and content, which pi-websearch's tavily backend reads. The key goes as a Bearer token, which is how pi-websearch sends apiKey.

Checked on November 12, 2026: the request pi-websearch builds for tavily, with query, max_results and include_domains, sent to this address, returned results from the domains asked for.

The Search API scores 97.9 F-score on all 1,000 SimpleQA Verified questions and 64.0 item F1 on all 200 WideSearch tasks. Scores and method.

Domain filters

pi-websearch sends a call's allowed_domains as include_domains and blocked_domains as exclude_domains, and SpecStream applies both. allowedDomains and blockedDomains in the file set the same filters for every search.

Keep DuckDuckGo as a backup

With a providers list, pi-websearch tries lower priority values first and moves to the next entry when one fails. This keeps the free DuckDuckGo HTML backend behind SpecStream:

Cost

Each search through this address is $1 per 1,000 searches of up to 10 results, from your balance, with no quote and no approval. Each started block of 10 more results adds $0.0012 to a call, so keep maxResults at 10 unless you need more. pi-websearch asks for at most 20. A search that returns nothing costs nothing. Each reply carries X-Balance-Cents, your balance in cents after the call.

Where the key lives

pi-websearch reads apiKey as written in the file. A project's .pi/websearch.json wins over the files in your home folder, so a project file without the key replaces SpecStream for that project. Give the key a spending limit under Agents & API.

For records with a source on every value, saved lists and monitors, add SpecStream's own Pi package as well. See SpecStream in Pi. Moving code that calls Tavily directly is covered in moving from Tavily.

Disconnect

Delete ~/.pi/websearch.json, and pi-websearch goes back to its defaults. Revoke the key under API keys in Agents & API. Questions go to [email protected].

More

SpecStream for pi-websearch covers what it does in pi-websearch on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and the matches are paid from your balance. Billing has the details. For help, email [email protected].