mateusdcc/pi-gpt-search

Purpose and runtime

pi-gpt-search is a TypeScript extension for the Pi Coding Agent that gives the active Pi model web retrieval without invoking GPT inference. It runs on Node.js 18+ and is installed/loaded by Pi as an extension. Primary extension entry point: src/index.ts.

Extension registration and user surfaces

The extension exposes three Pi-facing interfaces:

• /gpt-search direct command, registered through src/commands.ts.

• codex-search, a focused single-query LLM tool.

• web, a stateful multi-step research tool supporting search, document open, find, and navigation.

Tool construction and registration are centered in src/tool.ts, src/web-tool.ts, and src/index.ts.

Retrieval provider boundary

The provider abstraction separates Pi tool behavior from the remote retrieval backend. src/provider.ts defines the provider-facing boundary, while src/codex-provider.ts implements OpenAI Codex standalone search access. Requests target Codex/OpenAI retrieval infrastructure rather than a chat/completions API, preserving the “zero GPT inference” design.

Credentials, context, and privacy boundary

Authentication is sourced from explicit environment values or an existing local Codex session, with optional values documented in .env.example. src/context.ts manages request/session context, including the state needed for multi-step web operations. The intended outbound boundary is query and retrieval state only: conversation history, project files, and Pi system prompts are not sent as search payloads by default.

Core execution flow

For a direct command or codex-search, the flow is:

1. Pi invokes command/tool handlers in src/commands.ts or src/tool.ts.

2. Input is validated/normalized in src/normalize.ts.

3. The Codex provider in src/codex-provider.ts sends the retrieval request.

4. Results are transformed into Pi-facing output by src/output.ts.

For web, src/web-tool.ts accepts one or more search queries, then uses retained context to resolve returned reference IDs for later open and find operations. This makes research iterative while keeping retrieval orchestration within the extension.

Output, errors, and operational behavior

src/output.ts formats structured search results—such as titles, URLs, snippets, views, and citations—for Pi’s display/tool response layer. src/errors.ts provides a dedicated failure boundary for authentication, endpoint, timeout, cancellation, and upstream-response conditions. Debug request telemetry is controlled through PI_WEB_SEARCH_DEBUG; endpoint/session failures depend on Codex authentication validity and remote OpenAI service availability.

External dependencies and infrastructure

Material external systems are:

• Pi Coding Agent runtime, which loads src/index.ts and invokes registered commands/tools.

• Local Codex authentication state (typically ~/.codex/auth.json) or CODEX_ACCESS_TOKEN.

• OpenAI Codex standalone search endpoint (/codex/alpha/search) for search and document retrieval.

The package is distributed through npm/GitHub and configured as a Node/TypeScript package via package.json.