https://github.com/demigodmode/pi-web-agent
Reliable web tools for Pi: search for sources, fetch over HTTP, and use headless browsing only when explicitly requested.
https://github.com/demigodmode/pi-web-agent
coding-agent pi typescript web-fetch web-search
Last synced: 4 days ago
JSON representation
Reliable web tools for Pi: search for sources, fetch over HTTP, and use headless browsing only when explicitly requested.
- Host: GitHub
- URL: https://github.com/demigodmode/pi-web-agent
- Owner: demigodmode
- License: agpl-3.0
- Created: 2026-04-14T22:46:57.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-25T22:24:31.000Z (14 days ago)
- Last Synced: 2026-05-26T00:28:52.610Z (14 days ago)
- Topics: coding-agent, pi, typescript, web-fetch, web-search
- Language: TypeScript
- Size: 567 KB
- Stars: 21
- Watchers: 0
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# pi-web-agent
[](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@demigodmode/pi-web-agent)
[](https://demigodmode.github.io/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 direct links, 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
Compatibility notice: current `pi-web-agent` requires Pi 0.74+ because Pi packages moved to the `@earendil-works/*` scope. Update Pi before updating this package. If you are on an older Pi version, stay on `@demigodmode/pi-web-agent@0.6.x` until Pi is updated.
```bash
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 which web backends are configured.
Headless rendering first tries a detectable Chromium-family browser: Chrome, Chromium, Edge, or Brave. If none is found, it falls back to Playwright-managed Chromium and still launches headless. Firefox/Safari-only systems can still use search and plain HTTP reads; browser-rendered fallback uses Chromium.
Later on, update installed packages with:
```bash
pi update
```
## Docs
Docs site:
- https://demigodmode.github.io/pi-web-agent/
Work on the docs locally:
```bash
npm run docs:dev
```
Build the docs:
```bash
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:
```text
/web-agent settings
```
Helper commands:
```text
/web-agent doctor
/web-agent show
/web-agent changelog
/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:
```text
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:
```json
{
"presentation": {
"defaultMode": "compact",
"tools": {
"web_explore": { "mode": "verbose" }
}
}
}
```
Backend config is also supported. Defaults remain DuckDuckGo search, plain HTTP fetch, and local-browser headless fallback with managed Chromium fallback configured.
Backend settings can be changed from:
```text
/web-agent settings
```
Choose **Backends** to edit search/fetch providers, fallback behavior, and SearXNG or Firecrawl base URLs interactively. Firecrawl API keys should stay in environment variables rather than being written into config files.
If you already run SearXNG or Firecrawl, see the self-hosted backend guide:
- https://demigodmode.github.io/pi-web-agent/self-hosted-backends
## Local development
```bash
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`.