Pi Web Access

A Pi Coding Agent extension that provides bounded, SSRF-aware web retrieval plus explicitly opt-in GitHub, PDF, video, fallback-fetch, and web-search capabilities.

Security model: core web retrieval only permits public HTTP(S) targets. All advanced capabilities are disabled by default. Search and video providers are never contacted without a configured key. GitHub operations clone to a temporary directory, but edit and pull-request actions can modify a repository—use a sandbox repository for testing.

Features

Capability	Tool / command	Default	Notes
Bounded retrieval	web_fetch	enabled	Text, HTML, JSON, links, or headings; cache; auth; timeout; redirect validation.
Concurrent retrieval	web_fetch_many	enabled	Up to five URLs; one failure does not discard other results.
Cached passages	web_get_content	enabled	Slice cached content or find matching text.
GitHub local operations	github_repo	disabled	Shallow clones, tree/read/history/branches, editing, and gh PR actions.
PDF extraction	web_fetch	disabled	Uses the optional pdftotext binary.
Fallback retrieval	web_fetch	disabled	Retries with an alternate user agent after direct-fetch failure.
Web search	web_search	disabled	Google Programmable Search, Brave, Parallel, or keyless DuckDuckGo, with automatic fallback.
Video understanding	video_understand	disabled	Gemini local-video analysis, optional frame extraction, and explicit YouTube download.
Configuration	/web-config	enabled	Interactive settings and secret entry.
Status / cleanup	/web-status, /web-cleanup	enabled	Inspect cache/features and remove cache/temp clones.

Requirements

• Node.js 20+ (for the runtime APIs used by the extension)
• Pi Coding Agent
• Optional local tools on PATH: pdftotext (Poppler), ffmpeg, git, gh, and yt-dlp.

Example for Ubuntu/Debian:

sudo apt update
sudo apt install -y poppler-utils ffmpeg git gh yt-dlp

On macOS, install the same optional tools with Homebrew; on Windows, install them through your preferred package manager. ffmpeg is only needed for frame extraction, gh for PR actions, and yt-dlp only for explicitly permitted YouTube downloads.

Install and load

From this repository:

npm install
npm run build
npm test

For a one-off Pi session, load the TypeScript entry point directly:

pi -e ./src/index.ts

For project-local auto-discovery, create a .pi/extensions entry (the project must be trusted by Pi):

mkdir -p .pi/extensions
ln -s "$(pwd)/src/index.ts" .pi/extensions/pi-web-access.ts
pi

Use /reload after changing extension code or its configuration. Pi supports global extensions under ~/.pi/agent/extensions/ as well; see Pi's extension documentation for the installation method appropriate to your setup.

First-time configuration

The settings file is stored per user at:

~/.pi/pi-web-access.json

It is written with mode 0600. Do not commit it or share it, because it can hold API keys.

1. Start Pi with the extension and run /web-config.
2. Configure Core toggles, Limits and cache, and Domain policy and security as required.
3. In Optional features, enable only the capabilities you intend to use.
4. Add provider keys in Search provider credentials and Video provider credentials.
5. Select Save changes. Cache and rate-limit settings take effect immediately; feature settings are read for each tool call.
6. Run /web-status to confirm enabled optional features and cache status.

Safe testing defaults are a 5-minute cache TTL, 10 requests/minute/domain, and a 10-second timeout. The default blacklist contains malicious-site.com; a whitelist can be enabled when access must be restricted to approved domains.

Provider setup

Provider	Configuration	Free/testing resource
Gemini	In /web-config → Video provider credentials, choose Gemini and provide a key.	Create a key in Google AI Studio; review the current Gemini API pricing/free tier.
Brave	Add a Brave Search API key under Search provider credentials.	Use the Brave Search API documentation in a browser and verify the current trial/free quota.
Parallel	Add a Parallel key under Search provider credentials.	Create a key, review the docs, and check pricing.
Google	Add a Google API key and Programmable Search Engine ID under Google search credentials.	Create a Programmable Search Engine and enable its Custom Search JSON API in Google Cloud.
DuckDuckGo	No key required; select provider: "duckduckgo" or use auto.	HTML result availability/rate limits are controlled by DuckDuckGo.
GitHub	Enable GitHub, install gh, then authenticate for PR actions.	Use a separate free GitHub repository, never a production repo: gh auth login --web --git-protocol https.

Developers can register custom search or video providers programmatically through PiWebAccessExtension.addSearchProvider() and addVideoProvider(). Custom providers own their credentials and transport; the configuration UI deliberately exposes only bundled Gemini video setup.

Tools

web_fetch

Fetch one public HTTP(S) URL.

web_fetch({
  url: "https://example.com",
  extract: "text",                 // text | html | json | links | headers
  max_length: 4000,                  // 100–50,000
  bypass_cache: false,
  timeout: 10000,
  page_start: 1,                     // PDF only
  page_end: 1,                       // PDF only
  auth: { username, password, token, api_key }
})

text converts HTML to lightweight readable Markdown. Response output is bounded, while response bodies are also limited before processing. Requests to localhost, private/reserved IP ranges, and redirect targets resolving to those ranges are rejected.

web_fetch_many

Fetch one to five URLs concurrently:

web_fetch_many({
  urls: ["https://example.com", "https://api.github.com"],
  extract: "text",
  max_length: 4000
})

Each URL has an independent result. A failed URL is reported inline with successful ones.

web_get_content

Retrieve content previously cached by web_fetch in the same extraction mode:

web_get_content({ url: "https://example.com", extract: "text", offset: 0, limit: 1000 })
web_get_content({ url: "https://example.com", extract: "text", find_text: "Example" })

github_repo

Enable GitHub first. Use read-only actions against a public fixture such as https://github.com/octocat/Hello-World.

github_repo({ url: "https://github.com/octocat/Hello-World", action: "tree" })
github_repo({ url: "https://github.com/octocat/Hello-World", action: "read", path: "README" })
github_repo({ url: "https://github.com/octocat/Hello-World", action: "history" })
github_repo({ url: "https://github.com/octocat/Hello-World", action: "branches" })

Supported actions are summary, tree, read, history, branches, switch, edit, pull_requests, and create_pull_request.

• summary is for a GitHub issue or PR URL and requires authenticated gh.
• Repositories are shallow-cloned into private managed temporary directories. A repository used through github_repo is retained only for the current session so edit/switch/PR actions can build on earlier actions; /web-cleanup and session shutdown remove it.
• edit, switch, and create_pull_request require an interactive confirmation. create_pull_request uses gh pr create; a branch must already exist, be committed, and be pushed.
• Use only a sandbox repository for mutating actions.

web_search

Enable search and configure at least one key:

web_search({ query: "Pi Coding Agent", provider: "auto" })
web_search({ query: "Pi Coding Agent", provider: "brave", domain_filter: ["github.com"] })
web_search({ query: "Pi Coding Agent", provider: "parallel", domain_filter: ["-example.com"] })

auto tries configured Google, Brave, and Parallel providers, then DuckDuckGo as a keyless final fallback. Select google, brave, parallel, or duckduckgo explicitly when needed. A domain filter without - includes only that domain/subdomains; one prefixed with - excludes it.

video_understand

For Gemini, supply a permitted local video within the configured Maximum Gemini upload / YouTube download size (1–18 MiB; default 18 MiB):

video_understand({
  url: "/tmp/pi-web-access-sample.mp4",
  question: "Describe this scene.",
  timestamp: "0",
  extract_transcript: true,
  extract_frames: 2
})

Use a small, no-license-restriction test MP4 from Samplelib. Frame extraction requires ffmpeg. Remote YouTube URLs are metadata-only unless the separate YouTube-download opt-in is enabled; downloading must be limited to media you own or are explicitly permitted to download.

Testing

MANUAL_TEST_PLAN.md is the complete Ubuntu manual test checklist. It covers configuration, tools, safety failures, cache persistence, fallback behavior, PDF extraction, GitHub sandbox/PR preparation, Brave/Parallel behavior, Gemini/video/frame tests, free resources, and cleanup.

Automated local checks:

npm test                 # Jest unit tests
npm run lint             # TypeScript type check
npm run build            # compile to dist/
npm run benchmark:memory # Node fetch baseline (not an extension security test)

Security and operational notes

• Treat all API keys, auth objects, and video files as sensitive. Do not paste secrets into prompts, logs, screenshots, or version control.
• auth headers are forwarded to the requested public URL. Use only a destination you trust and a least-privilege test credential.
• Domain policy is checked before fetches. SSRF validation also checks DNS resolution and redirects.
• Cache content persists under ~/.pi/pi-web-access-cache; it may contain retrieved data. Run /web-cleanup to remove it.
• Search provider plans, free allowances, and geographic eligibility change. Confirm current terms in the provider dashboard before testing.
• The extension does not bypass paywalls, access controls, robots restrictions, or media licensing requirements.

Troubleshooting

Symptom	Resolution
Feature still says disabled after configuration	Select Save changes in /web-config, then rerun the tool.
pdftotext missing	sudo apt install poppler-utils, verify command -v pdftotext, then /reload.
yt-dlp missing	Install yt-dlp via apt or pipx, start a new shell if using pipx, then /reload.
Search says key is not configured	Add or replace the key in /web-config, then select Save changes.
Gemini says no provider/key	Select Gemini, add the key, and select Save changes.
GitHub PR action fails	Run gh auth status; ensure the sandbox branch exists, is committed, and has been pushed.
Fetch is blocked	Check whitelist/blacklist settings and ensure the URL and every redirect resolve to public addresses.
web_get_content has no entry	Run web_fetch first using the identical normalized URL and extract mode.

License

MIT.