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, meaning0 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 existingcodex 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 (runcodex login
in terminal, or setCODEX_ACCESS_TOKEN
in.env
).
If you prefer manual placement instead of pi install
:
mkdir -p ~/.pi/agent/extensions
cp -r pi-gpt-search ~/.pi/agent/extensions/
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
:
CODEX_ACCESS_TOKEN=your_token_here
CODEX_ACCOUNT_ID=your_account_id_here
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 provingzero-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- Deep architectural breakdown of modules, data flow, TUI renderers, context isolation, and cancellation.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 runningcodex login
to re-authenticate.
MIT License.