pi-codex-web-search

Pi extension that registers a web_search tool backed by your local codex CLI.

It is designed for the case where:

• you already use codex
• you are already authenticated with codex login
• you do not want to manage a separate API key inside the extension

How it works

When Pi calls web_search, the extension auto-resolves a usable Codex binary, then runs Codex non-interactively:

• codex exec --json
• -c web_search="cached" or -c web_search="live"
• read-only sandbox
• ephemeral session
• structured JSON output enforced with --output-schema
• final assistant message captured with --output-last-message

Codex's official web-search modes are disabled | cached | live. This extension uses cached and live explicitly per tool call. In Codex CLI terms, --search is equivalent to live web search.

The extension then:

• parses Codex JSONL events to show search progress in Pi
• tracks the actual search queries Codex issued across multiple item event shapes
• keeps page opens/find-in-page activity separate so document inspection does not incorrectly consume the query budget
• keeps a running search counter in the tool UI
• shows clearer in-flight status when fast mode nears its budget or auto-escalates
• uses persisted defaults for mode, freshness, and per-mode source caps unless the tool call overrides them
• records when a default fast search had to be retried as deep/live
• uses Defuddle for direct URL-only requests and supports optional URL fallback when Codex cannot produce a usable result
• returns a concise summary plus numbered sources with URLs and snippets

Requirements

• Node.js 22+
• authenticated Codex CLI session
• Codex CLI either:
  • available in PATH, or
  • installed in a common npm location the extension can auto-detect, or
  • pointed to explicitly with PI_CODEX_WEB_SEARCH_CODEX_PATH

Check your Codex auth state with:

codex login status

If needed, authenticate with:

codex login

Install

From npm:

pi install npm:pi-codex-web-search

From the repository path:

pi install /absolute/path/to/pi-codex-web-search

Or load directly during development:

pi -e ./src/index.ts

For hot reload, place the extension in one of Pi's extension folders and run /reload.

Tool

web_search

Parameters:

• query: string — what to search for
• maxSources?: number — optional cap from 1 to 10. If omitted, the saved fast/deep default is used for the chosen mode.
• mode?: "fast" | "deep" — optional depth override. If omitted, the saved default mode is used.
• freshness?: "cached" | "live" — optional freshness override. Use live for time-sensitive questions.

Behavior:

• uses the local Codex CLI
• requires a non-empty query
• defaults to saved settings of:
  • default mode = fast
  • fast freshness = cached
  • deep freshness = live
  • fast max sources = 5
  • deep max sources = 5
• supports explicit deep mode for broader research
• supports explicit cached/live freshness overrides
• keeps cached as the default for normal fast lookups and only auto-promotes to live for strong recency cues like today, latest, current, now, weather, price, breaking, and urgent
• uses Defuddle immediately when the query is just a URL (including https://defuddle.md/<url> mirrors) when defuddle-mode allows direct extraction
• automatically retries one recoverable default fast search as deep + live when Codex times out, burns through the fast query budget, loses transport, or fails to emit a usable final response
• strengthens the Codex prompt with hard budget awareness plus targeted guidance for site-constrained and documentation-style queries
• shows reconnects, WebSocket-to-HTTPS fallback, and the final classified failure cause in tool progress/details when they happen
• can fall back to Defuddle for single-URL extraction-style requests when Codex still fails after its own retries, if defuddle-mode enables fallback
• falls back to Codex's final JSONL agent message if --output-last-message comes back empty, including newer raw response.output_item.* assistant events as a compatibility path
• tolerates fenced or wrapped JSON when Codex produces the right object with extra surrounding text
• treats turn.failed, response.*.failed, and error JSONL events as first-class failure signals
• enforces smaller time/query budgets in fast mode so lightweight lookups do not run indefinitely
• counts only real web searches against those budgets, not open_page or find_in_page follow-up actions
• warns when fast mode has consumed its full query budget and is about to fail or auto-escalate
• blocks repeated fast-mode retries within the same turn after fast mode has already been exhausted
• shows live search queries and a running search counter in Pi's tool UI
• supports expanded tool details with Ctrl+O
• returns a compact answer with sources
• truncates oversized output and saves the full result to a temp file when needed
• surfaces clearer Codex auth guidance, including codex login status and codex login, when authentication appears to be missing or expired
• soft-degrades recoverable Codex failures so Pi can keep going, while still failing clearly for missing codex, bad local config, cancellations, and auth problems

Settings

Use the slash command below to persist defaults across sessions:

/web-search-settings

The interactive dialog is grouped into:

• Search defaults
• Defuddle behavior
• Timeouts
• Query budgets

You can also use direct subcommands:

/web-search-settings status
/web-search-settings default-mode deep
/web-search-settings fast-freshness cached
/web-search-settings deep-freshness live
/web-search-settings fast-max-sources 5
/web-search-settings deep-max-sources 5
/web-search-settings default-max-sources 5
/web-search-settings defuddle-mode direct
/web-search-settings fast-timeout-ms 90000
/web-search-settings deep-timeout-ms 240000
/web-search-settings defuddle-timeout-ms 45000
/web-search-settings fast-query-budget 10
/web-search-settings deep-query-budget 24
/web-search-settings reset

Notes:

• default-max-sources is kept as a compatibility alias and updates both fast-max-sources and deep-max-sources.
• The settings file is stored under your Pi agent directory and is reused by future sessions.
• Defaults include defuddle-mode = direct for URL-only extraction without surprising non-URL search behavior.
• Timeouts and search-query budgets are configurable for both fast and deep modes.

Note: current Codex docs describe the top-level web_search setting as the supported configuration surface. Older legacy settings such as features.web_search_request are deprecated.

Example

Ask Pi something like:

Search the web for the latest Codex CLI release notes and summarize the key changes.

Pi can call:

{
  "query": "latest Codex CLI release notes",
  "maxSources": 3
}

Development

pnpm install
pnpm run check

Release

This repo includes a manual GitHub Actions release workflow modeled after the one used in pi-copilot-queue.

Requirements:

• NPM_TOKEN GitHub Actions secret configured for the repository
• permissions to run the Release workflow

You can trigger it from GitHub Actions with a patch, minor, or major bump, plus an optional first-release flag.

Local equivalents:

pnpm run release
pnpm run release:first

Notes

• This extension does not register the native OpenAI Responses web_search tool directly inside Pi.
• Instead, it exposes a Pi tool that delegates web research to the locally installed Codex CLI.
• That keeps auth and web-search behavior aligned with your existing Codex setup.

License

MIT