Getting started

If you just want to try the package in Pi, this is the short version.

Install it

Check the Pi and Node requirements first.

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

If Pi is already running, reload or restart it so the package gets picked up.

Then run:

/web-agent doctor

That checks the extension, runtime dependency, and browser detection status.

What you get

The package exposes one public web research tool:

• web_explore

Use it when you want Pi to find and compare current web sources.

web_explore handles the annoying parts internally: search, HTTP reads, targeted headless rendering, source ranking, source-quality checks, and caveats when the evidence is not strong enough.

Try a prompt

Find current docs and discussions about configuring Vitest coverage in TypeScript projects.

Pi should call web_explore and return a compact research result. If you need more detail inline, switch presentation mode to preview or verbose.

Another example:

Find two or three current sources on DuckDuckGo HTML scraping in Node.js and tell me what the common parsing pitfalls are.

Prefer web_explore for that research. If the first pass is thin, Pi can call it again with a narrower query; Pi can also use tools the user requests for the task.

You can also include direct links in the prompt. web_explore reads HTTP/HTTPS links first, strips common tracking params, and then searches if it still needs more evidence.

For GitHub, PDF, and YouTube links, web_explore fetches the real content automatically instead of scraping the page. GitHub files, issues, PRs, and repo READMEs come from the raw/API endpoints; PDFs are extracted to text; YouTube links return the transcript. Public GitHub content is keyless; private GitHub content needs GITHUB_TOKEN or gh auth login. Scanned PDFs and videos without captions are noted rather than failing. Pasting a link and asking to summarize returns the extracted content (long transcripts or PDFs capped around 24k characters), so it's a reliable way to get summaries of videos, PDFs, or repo files.

If you paste a link to a whole GitHub repo (or a folder inside one), web_explore clones that exact commit and answers from the code, with citations that point at the commit it read. That needs git 2.32 or newer; public repositories can be read anonymously, while private repositories use gh auth login or GITHUB_TOKEN. If the repo can't be read, it says why. Press Esc if a run is taking too long; it stops everything underneath.

Presentation defaults

The package renders web research output in compact mode by default.

If you want to change that, open the action menu with:

/web-agent

From there you can open settings, show config, run doctor, or reset config. Settings lets you change presentation modes and backend providers without editing JSON by hand.

If you want the full details, see Presentation and settings.

Optional backends

By default, web_explore uses DuckDuckGo HTML search, plain HTTP page reads, and local-browser headless rendering with managed Chromium fallback when needed.

If you want a hosted search backend, SearXNG, or Firecrawl, open:

/web-agent settings

Choose Backends to point search at Brave, You.com, Exa, Tavily, Parallel (keyless), SearXNG, or a hosted Google SERP endpoint, and page reading at Firecrawl. The settings UI can edit providers, base URLs where relevant, and fallback behavior.

The hosted search backends each read a key from the environment: PI_WEB_AGENT_BRAVE_API_KEY for Brave, YDC_API_KEY for You.com, EXA_API_KEY for Exa, TAVILY_API_KEY for Tavily, PI_WEB_AGENT_GOOGLE_SERP_API_KEY for a Google SERP endpoint. Set the one you want, then choose that provider under Backends. None of them needs a baseUrl except google-serp, which takes the endpoint you point it at, and each only handles source discovery; web_explore still fetches pages, ranks evidence, and writes caveats itself.

Use /web-agent show to confirm the effective backend config. Use /web-agent doctor to check configured backend health.

Backend config also supports explicit fallback and a small set of provider options. See Backends for the full shape.

If your Firecrawl instance requires an API key, prefer an environment variable instead of committing secrets into project config:

PI_WEB_AGENT_FIRECRAWL_API_KEY=...

The settings UI does not write API keys. You can still set backends.fetch.apiKey manually for local-only setups, but env vars are the safer default.

This project only connects to existing SearXNG/Firecrawl services; it does not manage or document how to run those services.

Browser rendering requirement

Headless rendering first tries a detectable Chromium-family browser: Chrome, Chromium, Edge, or Brave.

If none is found, it tries Playwright-managed Chromium, which must already be installed. See Browser rendering for the command that installs the browser matching the package's Playwright version. Firefox/Safari-only systems can still use search and plain HTTP reads.

One thing to keep in mind

If the package says no usable evidence was found, or adds a caveat, that is intentional. It is better to admit the research pass was thin, narrow, blocked, or cautionary than to turn weak pages or bot-check screens into fake confidence.