# I reverse-engineered Codex's web search for use with Claude, and any local model

> Source: <https://github.com/mateusdcc/pi-gpt-search>
> Published: 2026-08-11 10:17:01+00:00

Native, Model-Independent Web Search for Pi using OpenAI Codex Standalone Search Engine.

`pi-gpt-search`

gives **any** Pi model (Gemini, Claude, local models, OpenRouter) real-time web search capabilities by reusing OpenAI Codex's standalone web retrieval infrastructure - with **ZERO GPT Model Inference Turns** and **ZERO GPT Tokens Consumed**.

Install via npm:

```
pi install npm:pi-gpt-search
```

Or install via GitHub:

```
pi install https://github.com/mateusdcc/pi-gpt-search
```

Or install project-locally for your current repository (`-l`

flag):

```
pi install npm:pi-gpt-search -l
```

Or try it temporarily in a single session without installing:

```
pi -e npm:pi-gpt-search
```

- 🚀
**Zero GPT Tokens Spent:** Pure web retrieval via OpenAI's backend endpoint. No GPT/Codex LLM turns are executed, meaning**0 input tokens, 0 output tokens, and 0 reasoning credits are billed**. - 👑
**Model Sovereign:** Your active Pi model (e.g., Gemini 3.5 Flash / Gemini 3.1 Pro) remains the sole reasoning model. - 🛠️
**Slash Command & LLM Tools:** Works both automatically as LLM tools (`codex-search`

&`codex-research`

) and as a direct user command (`/gpt-search`

). - 🔑
**Credential Reuse:** Automatically uses your existing`codex login`

session (`~/.codex/auth.json`

) or custom`.env`

tokens. - 🛡️
**Data Privacy:** Query-only by default. Does not send conversation history, project files, or system prompts to search.

```
Pi Coding Agent
 └── Gemini (or active model)
      ├── codex-search(query: "latest Rust release")
      │    └── Codex/OpenAI Standalone Search API (/codex/alpha/search)
      │         └── Structured Results (Title, URL, Snippet)
      │              └── Gemini continues reasoning & answers user
      │
      └── codex-research(search_query: [...], open: [...], find: [...])
           └── Multi-Step Web Research Harness
                └── Deep document content, pattern matching & citations
```

Run either Codex tool yourself without spending LLM tokens:

```
/codex-search Rust 1.97 release notes
/codex-research OpenAI Codex GitHub repository
```

Use `codex-search`

for a quick lookup and `codex-research`

when you want more comprehensive results. The direct commands preserve their tool defaults: `short`

for `codex-search`

and `long`

for `codex-research`

.

`/gpt-search <query>`

remains available as a simple legacy alias.

Ask any model a question requiring current facts (single-query lookup):

```
pi --model antigravity/gemini-3.5-flash "What is the latest release of Rust and what changed?"
```

The model uses it automatically for quick lookups that need current information.

```
[PI_WEB_SEARCH_DEBUG] req_id=maqk8a5 query="latest Rust release version and date 2026" provider=codex
[PI_WEB_SEARCH_DEBUG] req_id=maqk8a5 status=200 elapsed_ms=1863 results=41
```

Ask models to conduct deep, iterative web research with multi-query execution, page content inspection, pattern finding, and link navigation. The model manages the research steps and sources for you.

The pre-rename tool name `web`

is kept as a backward-compatible alias. It delegates to the same implementation as `codex-research`

and prepends a deprecation notice on every invocation. New integrations should use `codex-research`

directly.

**Pi Coding Agent:**`pi`

CLI installed (`v0.80+`

).**Node.js:**`v18.0.0`

or higher.**OpenAI Codex Auth:** An authenticated Codex session (run`codex login`

in terminal, or set`CODEX_ACCESS_TOKEN`

in`.env`

).

If you prefer manual placement instead of `pi install`

:

```
# Global (All projects)
mkdir -p ~/.pi/agent/extensions
cp -r pi-gpt-search ~/.pi/agent/extensions/

# Project-local
mkdir -p .pi/extensions
cp -r pi-gpt-search .pi/extensions/
```

Copy `.env.example`

to `.env`

if you want to explicitly override your Codex access token:

```
cp .env.example .env
```

Edit `.env`

:

```
# Optional: If unset, automatically reads ~/.codex/auth.json
CODEX_ACCESS_TOKEN=your_token_here
CODEX_ACCOUNT_ID=your_account_id_here

# Enable debug logging
PI_WEB_SEARCH_DEBUG=1
```

Security Note:Never commit`.env`

to Git.`.env`

is listed in`.gitignore`

.

`pi-gpt-search`

comes with a 4-level test suite:

```
npm test
```

Test suite breakdown:

**Unit Tests (** Schema validation, DTO normalization, error classes, output formatting, collapsible display.`unit.test.ts`

,`commands.test.ts`

,`normalize.test.ts`

,`output.test.ts`

,`web-tool.test.ts`

):**Integration Tests (** Mock server handling for 200, 401, 403, 429, 500, timeouts, cancellation.`provider-integration.test.ts`

):**Real Search Test (** Live execution against OpenAI's search endpoint and session continuity.`real-search.test.ts`

&`real-endpoint.test.ts`

):**Zero-GPT Verification (** Network interception test proving`zero-gpt.test.ts`

):**0 GPT inference calls** are made.**E2E Research Harness Suite (** Full end-to-end multi-step web research test suite.`e2e-research.test.ts`

):

[HOW-IT-WORKS.md](/mateusdcc/pi-gpt-search/blob/main/HOW-IT-WORKS.md)- Deep architectural breakdown of modules, data flow, TUI renderers, context isolation, and cancellation.[HOW-IT-WAS-EXTRACT.md](/mateusdcc/pi-gpt-search/blob/main/HOW-IT-WAS-EXTRACT.md)- Reverse-engineering guide documenting how the standalone search endpoint was discovered.

**Search Index Scope:** Returns search result snippets, URLs, and document views; does not include a full headless browser DOM renderer.**Session Auth:** Requires an active ChatGPT/Codex login session (`codex login`

). Expired sessions require running`codex login`

to re-authenticate.

MIT License.