pi-web-tools

Web access tools for Pi: search, deep research, content fetch, and code search.

For the Exa-specific API map and tool semantics, see EXA.md.

Highlights

• web_search with provider selection: auto, exa, perplexity, gemini, exa-mcp, duckduckgo, openai-native.
• web_research runs Exa Deep Search with lite, standard, or full modes. Writes findings reports with raw-metadata sidecars.
• web_fetch extracts GitHub repos (clone cache), URL and local PDFs, HTML/text/JSON, YouTube and local video, with Jina Reader fallback on blocked pages.
• web_answer and web_find_similar for Exa-first quick answers.
• code_search uses Exa Code /context with fallback to code-focused Exa search.
• get_web_content retrieves stored full content by id — no refetch.
• OpenAI-native web_search rewrite on supported Codex models.

auto provider tries keyed providers first (Exa, Perplexity, Gemini API), then no-key fallbacks (Exa MCP, DuckDuckGo), then Gemini Web cookies if enabled, then openai-native.

Install

Via npm:

pi install npm:@vanillagreen/pi-web-tools

Via vstack:

cargo install --git https://github.com/vanillagreencom/vstack.git vstack
vstack add vanillagreencom/vstack --pi-extension pi-web-tools --harness pi -y

Restart Pi after installation.

Commands

| Command | Action | | --- | --- | | /web-tools | Open settings (or print status if extension-manager isn't installed). | | /web-tools:doctor | Show status and diagnostics. | | /web-tools:provider:<name> | Switch the active provider for this session. |

Fetch storage

web_fetch returns a compact preview and stores extracted content in the current Pi session under a generated content id (e.g. web-...). Use get_web_content with that id to retrieve the stored text — it doesn't refetch the URL.

• GitHub, direct HTTP, and PDF paths store full extracted text before preview truncation.
• Exa-provider paths (provider=exa and auto-mode Exa fallback) store provider-capped excerpts (default 6000 chars; override per call with textMaxCharacters). get_web_content labels these as stored excerpt so the caller knows to set a larger cap or fetch directly if it needs the full document.
• Local PDFs supported via filePath/filePaths, file://..., or PDF-looking paths.
• textMaxCharacters caps the immediate preview (default 4k chars).
• get_web_content.maxCharacters caps retrieval (default 50k chars).

Multi-URL preview caps

A single web_fetch call accepts many URLs via urls/filePaths. To keep content[0].text from blowing past the model's input window, multi-URL calls cap the aggregate preview size and emit a manifest for large batches. Single-URL calls and explicit textMaxCharacters opt-ins are unaffected.

| URLs in call | Per-URL preview | Aggregate cap | Format | | --- | --- | --- | --- | | 1 | textMaxCharacters (default 4k) | — | preview blocks | | 2–5 | min(textMaxCharacters, floor(16 KB / count)) | 16 KB | preview blocks | | 6+ | 512 chars head | 25 KB | manifest of all URLs + short preview heads |

The sidecar (pi-web-tools.content events + get_web_content) stores per-URL full extracted text for direct/GitHub/PDF/HTTP paths and provider-capped excerpts for Exa paths. The aggregate cap only applies to the inline preview returned to the model. Pass textMaxCharacters to opt back into larger inlined previews when the caller knows the context budget allows it; for Exa paths the same flag also raises the provider-side excerpt cap.

API keys

Set via environment variables, project .env.local/.env, or a private config file. Process env wins over files.

• EXA_API_KEY
• PERPLEXITY_API_KEY
• GEMINI_API_KEY
• OPENAI_API_KEY
• JINA_API_KEY (optional; anonymous Jina Reader works without it)
• PI_WEB_TOOLS_CONFIG_FILE=/path/to/private.json

Values may be 1Password references such as op://Private/Exa API Key/credential when the op CLI is installed and signed in. References resolve best-effort with a short startup timeout (default 1500 ms, override with PI_WEB_TOOLS_OP_READ_TIMEOUT_MS); unresolved references are treated as unset so Pi startup does not block.

Deep research modes

| Mode | Exa type | Results | Text cap | Highlight cap | | --- | --- | ---: | ---: | ---: | | lite | deep-lite | 15 | 10k | 600 | | standard | deep-reasoning | 50 | 16k | 900 | | full | deep-reasoning | 150 | 24k | 1200 |

standard and full request Exa summaries and structured output. full runs the primary query plus each additionalQueries entry, then dedupes URLs.

Override per-mode defaults with the Exa research mode overrides setting (JSON keyed by lite/standard/full).

Settings

Open /extensions:settings; settings appear under the Web Tools tab.

Project settings in .pi/settings.json apply only after Pi marks the workspace trusted; before trust, vstack Pi extensions read user/global settings only.

Glyph style: each package exposes glyphStyle (unicode default, ascii for terminal-safe chrome). @vanillagreen/pi-tool-renderer.globalGlyphStyleOverride=ascii forces ASCII chrome across vstack Pi extensions while leaving tool/model/user content unchanged.

General

| Setting | What it does | | --- | --- | | Auto-enable web tools | Add web tools to the active set while preserving Pi natives. | | Default provider | Provider used by web_search unless the call overrides. | | Enabled providers | Comma-separated allow-list. |

OpenAI native

| Setting | What it does | | --- | --- | | OpenAI native web_search | Rewrite web_search to native OpenAI/Codex Responses web_search. | | OpenAI external web access | Set external_web_access on native tools. |

Exa

| Setting | What it does | | --- | --- | | Exa deep research | Register and enable web_research. | | Exa research mode overrides | JSON object keyed by lite/standard/full. | | Exa advanced tools | Enable web_answer, web_find_similar, code_search. |

Content

| Setting | What it does | | --- | --- | | Jina Reader fallback | Fall back to r.jina.ai for blocked or 403/429/5xx pages. | | GitHub clone extraction | Use a clone cache for GitHub repo URLs. | | GitHub clone max size | Large-repo fallback threshold in MB. | | Video extraction | YouTube and local video understanding via Gemini. | | Browser cookie access | Opt-in browser cookie extraction for Gemini Web fallback. |

Compatibility

| Setting | What it does | | --- | --- | | Compatibility aliases | Register legacy aliases like fetch_content and web_search_exa. |

Notes

web_search moved here from pi-codex-minimal-tools. Install both updated packages together; pi-codex-minimal-tools now owns only image_generation, view_image, and apply_patch.