pi-web-agent

@demigodmode/pi-web-agent is a Pi package for web access.

Most agent web tools blur search, fetch, browser rendering, and research into one vague thing. pi-web-agent exposes one public research tool, web_explore, and keeps search/fetch/headless work inside that bounded workflow.

The point is keeping the model-facing boundary simple: ask web_explore to research a question, and it handles discovery, HTTP reads, targeted browser rendering, source ranking, and caveats internally.

That sounds obvious, but a lot of agent tooling gets fuzzy right there. This package is meant to be stricter about what it actually did and more willing to say when a read was not good enough to trust.

Install

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

After installing, reload or restart Pi. Run /web-agent for the action menu, or /web-agent doctor to check whether the package loaded cleanly and whether headless rendering can find a browser.

Headless rendering currently requires a detectable Chromium-family browser: Chrome, Chromium, Edge, or Brave. Firefox/Safari-only systems can still use search and plain HTTP reads, but browser-rendered fallback pages need a supported Chromium-family browser for now.

Later on, update installed packages with:

pi update

Docs

Docs site:

• https://demigodmode.github.io/pi-web-agent/

Work on the docs locally:

npm run docs:dev

Build the docs:

npm run docs:build

Presentation modes

pi-web-agent renders web tool output in one visible mode at a time:

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

See the v0.3.0 release notes for a before/after of the transcript cleanup:

• https://github.com/demigodmode/pi-web-agent/releases/tag/v0.3.0

Settings

Primary UI:

/web-agent settings

Helper commands:

/web-agent doctor
/web-agent show
/web-agent reset project
/web-agent reset global
/web-agent mode preview
/web-agent mode web_explore verbose
/web-agent mode web_explore inherit

Config files:

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

Precedence:

• built-in defaults
• global config
• project config

Project config overrides global config.

Example:

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

Backend config is also supported. Defaults are DuckDuckGo search, plain HTTP fetch, and local browser headless fallback:

{
  "backends": {
    "search": { "provider": "duckduckgo" },
    "fetch": { "provider": "http" },
    "headless": { "provider": "local-browser" }
  }
}

Self-hosted example for existing SearXNG/Firecrawl services:

{
  "backends": {
    "search": { "provider": "searxng", "baseUrl": "http://localhost:8080" },
    "fetch": { "provider": "firecrawl", "baseUrl": "http://localhost:3002" },
    "headless": { "provider": "local-browser" }
  }
}

Prefer PI_WEB_AGENT_FIRECRAWL_API_KEY for Firecrawl auth instead of putting secrets in project config. /web-agent doctor validates required backend fields and checks configured self-hosted endpoints.

Full guide: https://demigodmode.github.io/pi-web-agent/self-hosted-backends

Local development

npm install
npm test
npm run lint
npm run build

For local Pi work, this repo includes .pi/extensions/pi-web-agent.ts.

If Pi is already running, use /reload after changes.

License

AGPL-3.0-only. See LICENSE.