pi-web-agent

Appearance

Install ​

There are two real ways people end up using this project:

  • install the published package in Pi
  • work from the repo locally during development

The important thing is not to mix those up without meaning to, because Pi can end up loading a different copy than the one you think you are testing.

Requirements ​

Update Pi to 0.74 or newer before installing this package. Pi packages moved to the @earendil-works/* scope in that version. On older Pi, stay on @demigodmode/pi-web-agent@0.6.x. The extension works on Pi 0.99 and 1.0.

CI runs on Node 22. The locked runtime dependency undici@8.10.2 declares Node >=22.19.0; that is its dependency requirement, while this repo's CI covers the Node 22 line.

Install from npm in Pi ​

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

That installs the published package.

For the published package, Pi loads the compiled runtime from dist/extension.js through the pi.extensions entry in package.json.

After install/reload, run:

text
/web-agent doctor

That checks whether the package loaded and reports the configured search, fetch, and headless backends.

Browser rendering ​

Headless rendering first tries a local Chromium-family browser. Supported local browsers are Chrome, Chromium, Edge, and Brave when they can be detected on Windows, macOS, or Linux.

If none is detected, web_explore tries Playwright-managed Chromium with headless: true. That browser must already be installed; installing pi-web-agent does not download it. Firefox/Safari-only systems can still use search and plain HTTP reads.

To install the matching Chromium build, run the installed package's Playwright CLI as the same user who runs Pi. Start in the @demigodmode/pi-web-agent package directory. For Pi's default global npm installation:

bash
cd ~/.pi/agent/npm/node_modules/@demigodmode/pi-web-agent
node -e "const path = require('node:path'); require('node:child_process').execFileSync(process.execPath, [path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js'), 'install', 'chromium'], { stdio: 'inherit' });"

Adjust the directory for a project or custom installation. This resolves the Playwright dependency from that package directory, including a nested copy, so the browser matches the version Pi will load. If a package update changes Playwright, rerun the command. Linux also needs the browser's system libraries; see Playwright's browser installation and system requirements.

Doctor detects local browsers. Its managed Chromium fallback configured line describes the fallback configuration; it does not check that the managed browser exists or can launch.

Work from the repo locally ​

This repo also includes a project-local Pi extension entrypoint at .pi/extensions/pi-web-agent.ts.

That path is for local development and reloads while you are working in this repo.

Config files after install ​

The package stores presentation and backend settings in real JSON files.

Global config:

text
~/.pi/agent/extensions/pi-web-agent/config.json

Project config:

text
.pi/extensions/pi-web-agent/config.json

Project config overrides global config.

If you change settings through /web-agent, those files are what get updated.

Backend config ​

The default backend setup is:

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

For a self-hosted or hosted-backend setup, open:

text
/web-agent settings

Choose Backends to set:

  • search provider: duckduckgo, searxng, brave, youcom, exa, tavily, or google-serp
  • SearXNG URL, for example http://localhost:8080
  • Google SERP endpoint URL, for example https://google.serper.dev/search
  • fetch provider: http or firecrawl
  • Firecrawl URL, for example http://localhost:3002
  • optional fallback behavior

The hosted search backends don't need a baseUrl (except google-serp, which needs the endpoint of the vendor you use); each reads a key from the environment, then you pick the provider in /web-agent settings. They're discovery-only, so web_explore still reads pages, ranks sources, and writes caveats itself.

If your Firecrawl instance requires a key, prefer an environment variable:

text
PI_WEB_AGENT_FIRECRAWL_API_KEY=...

The settings UI does not write API keys. For local-only configs you can still add "apiKey": "..." to the fetch config manually. Saving Backends replaces that scope's backend section without the Firecrawl apiKey or proxy password, even if you edited another field. Use environment variables to keep those secrets through settings saves.

Run /web-agent doctor after changing backend config. It validates required baseUrl values, warns when a hosted search provider is selected without its key, checks hosted backends when a key is present, checks configured SearXNG/Firecrawl endpoints with a short timeout, and shows the network allow list and whether the upstream proxy is trusted to resolve names.

Backend config also supports explicit fallback and a small set of provider options. See Backends for the full shape, including all the hosted search providers.

Environment variables ​

Secrets live in the environment, not in config the settings UI writes. The ones the package reads:

  • PI_WEB_AGENT_BRAVE_API_KEY: Brave search
  • YDC_API_KEY: You.com search
  • EXA_API_KEY: Exa search
  • TAVILY_API_KEY: Tavily search
  • PI_WEB_AGENT_GOOGLE_SERP_API_KEY: Google SERP endpoint search (baseUrl + header key, any vendor)
  • PI_WEB_AGENT_FIRECRAWL_API_KEY: Firecrawl fetch
  • GITHUB_TOKEN: optional for public GitHub content; private GitHub reader and repo-research access need GITHUB_TOKEN or gh auth login

This package integrates with existing self-hosted services. SearXNG/Firecrawl installation, Docker Compose files, reverse proxies, TLS, and auth setup belong to those projects' docs.

Repo research needs git ​

Pasting a GitHub repo link makes web_explore clone that repo, so git 2.32 or newer has to be on your PATH. That's true on Windows, macOS, and Linux. Nothing else in the package needs git. /web-agent doctor has a repo research: line that shows your git version and where the GitHub token comes from.

Pi versions ​

The extension works on Pi 0.99 and 1.0. typebox is a peer dependency that Pi already provides to extensions, so if you installed an older version of this package, update or reinstall it so the old bundled copy goes away.

Watch out for mixed setups ​

If you have both the npm-installed package and the local repo-based extension in play, it gets easy to think you are testing one copy when Pi is actually loading the other.

We already ran into exactly that during development.

If behavior looks stale, missing, or just weird, check what Pi actually loaded before you debug anything else.

How to sanity-check what Pi loaded ​

A few practical checks help:

  • make a small visible local change and use /reload
  • restart Pi after install changes
  • check whether the behavior matches the local repo or the published package version
  • if needed, temporarily remove one install path so there is only one source of truth

It is a boring problem, but it is the kind that wastes a lot of time if you miss it.