pi-web-agent

One public tool, web_explore, that does bounded web research for Pi: search, fetch, targeted browser rendering, ranking, and honest caveats, all behind a single call.

Most agent web tooling blurs search, fetch, rendering, and synthesis into one vague thing. pi-web-agent keeps that boundary simple, and it is stricter about what it actually did: bot-check pages, narrow source sets, unreadable threads, and conflicting evidence show up as caveats instead of fake confidence.

What you get

• One tool. web_explore handles direct links, discovery, HTTP reads, targeted headless rendering, source ranking, source-quality checks, and caveats internally.
• Reads the real content behind links. Paste a GitHub, PDF, or YouTube URL and it pulls the actual thing (GitHub files/issues/PRs from the API, PDF text, YouTube transcripts), keyless. So "summarize this PDF" or "what does this repo do" works off the source, not the page shell.
• Answers questions about a GitHub repo from its code. Paste a repo or folder link and it clones that exact commit (shallow, over HTTPS), searches the code for your question, and cites excerpts with links pinned to the commit. Needs git 2.32+. Private repos work with gh auth login or GITHUB_TOKEN. If the repo can't be read it says why instead of guessing from the README.
• Esc stops it. Cancelling a running web_explore stops searches, page reads, and the headless browser. Page reads give up after 15 seconds (PDFs 60, Firecrawl 45), and one page that fails to load doesn't fail the whole run.
• Seven search backends. DuckDuckGo (keyless default), SearXNG, Brave, You.com, Exa, Tavily, and any Google SERP endpoint you point it at.
• Optional search fanout. Query several backends at once, dedupe, and rank pages that more than one provider agreed on to the top. Off by default; flip it to on or auto.
• Honest by default. Weak, narrow, blocked, or cautionary evidence gets flagged instead of dressed up as confidence.
• Safe with untrusted pages. Links the model picks, or finds on a page it read, can't reach localhost, your LAN, or cloud metadata endpoints. That includes redirects and everything a headless page loads. Addresses you configure yourself aren't affected, and an allow list covers the private ranges you do want.
• Fallback that knows why. Rate-limited or misconfigured backends get skipped for a while, flaky ones get one retry, and answers say when some search backends were unavailable.
• Bounded output. compact / preview / verbose transcript modes.
• Zero-config to start. Runs keyless out of the box (DuckDuckGo search, local browser, the built-in readers). Opt into hosted backends, fallback, search fanout, and per-tool output modes through config when you want more control.

Why pi-web-agent

Compared to other web tooling for agents:

• Hands-off. No curator, no browser windows to approve, no step that pops you out of your session. Ask web_explore once and the answer comes back cleanly. Nothing to babysit.
• Keyless by default. Search, page reads, and the GitHub/PDF/YouTube readers all work with no API keys. Add hosted providers only when you want them.
• Bounded and honest. Compact output by default, and it says when a read was not good enough instead of returning fake confidence.

Install

pi-web-agent requires Pi 0.74+ (Pi packages moved to the @earendil-works/* scope). Update Pi before updating this package. On older Pi, stay on @demigodmode/pi-web-agent@0.6.x. The extension works on Pi 0.99 and 1.0; typebox is a peer dependency that Pi already provides.

pi install npm:@demigodmode/pi-web-agent

Reload or restart Pi after installing, then:

/web-agent doctor   # check it loaded and show configured backends
/web-agent          # action menu

Update later with pi update --extensions.

Browser rendering: headless first tries a detected Chromium-family browser (Chrome, Chromium, Edge, Brave). If none is found, it falls back to Playwright-managed Chromium. Firefox/Safari-only systems still get search and plain HTTP reads.

Usage

Ask web_explore a web question:

Find current docs and discussions on configuring Vitest coverage with the v8 provider.

Or hand it a link to read:

Summarize this PDF: https://arxiv.org/pdf/1706.03762

If a pass comes back thin, call web_explore again with a narrower query.

Backends

Defaults are DuckDuckGo search, plain HTTP fetch, and local-browser headless. Switch providers from /web-agent settings → Backends. API keys stay in environment variables, never in config files.

Full config shape (fallback, SearXNG/Firecrawl options, fanout): see the self-hosted backends docs.

Settings

/web-agent settings                    # main UI
/web-agent doctor                      # health check
/web-agent show                        # effective config
/web-agent changelog
/web-agent mode web_explore verbose    # per-tool presentation mode
/web-agent reset project | global

Config is JSON, and project config overrides global:

Global:  ~/.pi/agent/extensions/pi-web-agent/config.json
Project: .pi/extensions/pi-web-agent/config.json

{
  "presentation": {
    "defaultMode": "compact",
    "tools": { "web_explore": { "mode": "verbose" } }
  }
}

Presentation modes:

• compact: short summary, the default everywhere
• preview: slightly richer bounded view
• verbose: fuller bounded view

Docs

Full docs: https://demigodmode.github.io/pi-web-agent/. Work on them locally with npm run docs:dev.

Development

npm install
npm test
npm run lint
npm run build

Local Pi work uses .pi/extensions/pi-web-agent.ts; run /reload after changes.

Feature and fix PRs target develop; main only moves on release. See Releases.

License

AGPL-3.0-only. See LICENSE.