# mateusdcc/pi-gpt-search architecture

> Architecture diagram of the GitHub repository mateusdcc/pi-gpt-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mateusdcc/pi-gpt-search
- Repository: https://github.com/mateusdcc/pi-gpt-search

## Overview

#### 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`.

Main entry points: [`src/codex-provider.ts`](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/codex-provider.ts) (Codex provider), [`src/web-tool.ts`](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/web-tool.ts) (web tool), [`src/index.ts`](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/index.ts) (Extension entry), [`src/output.ts`](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/output.ts) (Pi-facing output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pi["Pi Integration"]
  node_pi_runtime{{"Pi Coding Agent<br/>host runtime"}}
  node_entry["Extension entry<br/>registration<br/>[index.ts]"]
  node_command["/gpt-search<br/>Pi command<br/>[commands.ts]"]
  node_codex_tool["codex-search<br/>Pi tool<br/>[tool.ts]"]
  node_web_tool["web tool<br/>stateful Pi tool<br/>[web-tool.ts]"]
end

subgraph group_extension["Extension Core"]
  node_normalize["Input normalization<br/>validation layer<br/>[normalize.ts]"]
  node_context["Research context<br/>session state<br/>[context.ts]"]
  node_provider_boundary["Provider boundary<br/>retrieval interface<br/>[provider.ts]"]
  node_codex_provider["Codex provider<br/>retrieval client<br/>[codex-provider.ts]"]
  node_output["Pi-facing output<br/>result formatter<br/>[output.ts]"]
  node_errors["Failure boundary<br/>error handling<br/>[errors.ts]"]
end

subgraph group_remote["Credentials &amp; Retrieval"]
  node_credentials["Codex credentials<br/>local auth"]
  node_codex_endpoint{{"Codex search endpoint<br/>remote retrieval API"}}
end

node_pi_runtime -->|"loads"| node_entry
node_entry -->|"registers"| node_command
node_entry -->|"registers"| node_codex_tool
node_entry -->|"registers"| node_web_tool
node_command -->|"query"| node_normalize
node_codex_tool -->|"query"| node_normalize
node_web_tool -->|"search input"| node_normalize
node_web_tool -->|"stores references"| node_context
node_context -->|"resolves open/find"| node_web_tool
node_normalize -->|"normalized request"| node_provider_boundary
node_provider_boundary -->|"implemented by"| node_codex_provider
node_codex_provider -->|"authenticates with"| node_credentials
node_codex_provider -->|"retrieval request"| node_codex_endpoint
node_codex_endpoint -->|"results"| node_codex_provider
node_codex_provider -->|"structured results"| node_output
node_output -->|"display response"| node_command
node_output -->|"tool response"| node_codex_tool
node_output -->|"research response"| node_web_tool
node_codex_provider -.->|"operational failures"| node_errors

click node_entry "https://github.com/mateusdcc/pi-gpt-search/blob/main/src/index.ts"
click node_command "https://github.com/mateusdcc/pi-gpt-search/blob/main/src/commands.ts"
click node_codex_tool "https://github.com/mateusdcc/pi-gpt-search/blob/main/src/tool.ts"
click node_web_tool "https://github.com/mateusdcc/pi-gpt-search/blob/main/src/web-tool.ts"
click node_normalize "https://github.com/mateusdcc/pi-gpt-search/blob/main/src/normalize.ts"
click node_context "https://github.com/mateusdcc/pi-gpt-search/blob/main/src/context.ts"
click node_provider_boundary "https://github.com/mateusdcc/pi-gpt-search/blob/main/src/provider.ts"
click node_codex_provider "https://github.com/mateusdcc/pi-gpt-search/blob/main/src/codex-provider.ts"
click node_output "https://github.com/mateusdcc/pi-gpt-search/blob/main/src/output.ts"
click node_errors "https://github.com/mateusdcc/pi-gpt-search/blob/main/src/errors.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pi_runtime,node_entry,node_command,node_codex_tool,node_web_tool toneBlue
class node_normalize,node_context,node_provider_boundary,node_codex_provider,node_output,node_errors toneAmber
class node_credentials,node_codex_endpoint toneMint
```

## Components

### Pi Integration

- **Pi Coding Agent**: host runtime · Loads the extension and invokes its commands and tools.
- [Extension entry](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/index.ts): registration · `src/index.ts`
- [/gpt-search](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/commands.ts): Pi command · `src/commands.ts`
- [codex-search](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/tool.ts): Pi tool · Focused single-query retrieval tool. · `src/tool.ts`
- [web tool](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/web-tool.ts): stateful Pi tool · Supports iterative search, open, find, and navigation. · `src/web-tool.ts`

### Extension Core

- [Input normalization](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/normalize.ts): validation layer · `src/normalize.ts`
- [Research context](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/context.ts): session state · Retains reference IDs for follow-up web operations. · `src/context.ts`
- [Provider boundary](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/provider.ts): retrieval interface · `src/provider.ts`
- [Codex provider](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/codex-provider.ts): retrieval client · Uses standalone retrieval rather than chat/completions inference. · `src/codex-provider.ts`
- [Pi-facing output](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/output.ts): result formatter · Formats titles, URLs, snippets, views, and citations. · `src/output.ts`
- [Failure boundary](https://github.com/mateusdcc/pi-gpt-search/blob/main/src/errors.ts): error handling · Handles auth, endpoint, timeout, cancellation, and upstream failures. · `src/errors.ts`

### Credentials & Retrieval

- **Codex credentials**: local auth · Uses CODEX_ACCESS_TOKEN or local Codex session state.
- **Codex search endpoint**: remote retrieval API · OpenAI /codex/alpha/search for search and document retrieval.

## Connections

- Pi Coding Agent → Extension entry: loads
- Extension entry → /gpt-search: registers
- Extension entry → codex-search: registers
- Extension entry → web tool: registers
- /gpt-search → Input normalization: query
- codex-search → Input normalization: query
- web tool → Input normalization: search input
- web tool → Research context: stores references
- Research context → web tool: resolves open/find
- Input normalization → Provider boundary: normalized request
- Provider boundary → Codex provider: implemented by
- Codex provider → Codex credentials: authenticates with
- Codex provider → Codex search endpoint: retrieval request · Only query and retrieval state are sent by default.
- Codex search endpoint → Codex provider: results
- Codex provider → Pi-facing output: structured results
- Pi-facing output → /gpt-search: display response
- Pi-facing output → codex-search: tool response
- Pi-facing output → web tool: research response
- Codex provider → Failure boundary: operational failures