pi-codex-search

Search the web in Pi through your Codex subscription.

Pi keeps the harness small. Codex already has a ChatGPT-backed search path. This package connects the two: it adds a codex_search tool to Pi and uses the same openai-codex login Pi already knows about.

No ACCESS_TOKEN env var. No separate login flow. If Pi can use your Codex subscription, this extension can use the same auth.

Why this exists

Web search does not have to be built into Pi. It can be a tool.

This extension is for Pi workflows that need fresh or source-backed information:

• Look up current docs and release notes. Ask the model to check things that changed after its training cutoff.
• Get sources with the answer. Search results include citations when Codex returns them.
• Reuse your Codex login. The tool uses Pi's existing openai-codex OAuth credential instead of asking you to paste tokens.
• Batch related searches. One tool call can run up to five related queries in parallel and return the results grouped by query.
• Keep projects in control. Rename the tool, change defaults, or disable it per project.

What this package adds

• A codex_search Pi tool.
• 1–5 search queries per call, run in parallel.
• live or cached freshness, plus low / medium / high search context size.
• Streaming progress while Codex responds.
• Collapsed result previews in the TUI, with full text and sources available when expanded.
• Structured details: model, citations, search calls, response ids, usage, and per-query failures.
• Config files for home and project defaults.
• /codex-search-settings for status, editing, reset, rename, and disable.

Install

From npm:

pi install npm:pi-codex-search

Or load a local checkout without installing:

pi -e /path/to/pi-codex-search

Install from GitHub Release tarball

If you prefer not to use npm, download the tarball from the latest release, extract it, and install from the local path:

curl -L https://github.com/Leechael/pi-codex-search/releases/latest/download/pi-codex-search.tar.gz | tar -xz -C /tmp
pi install /tmp/pi-codex-search

Sign in

Inside Pi, run:

/login openai-codex

Choose ChatGPT Plus/Pro (Codex Subscription) if Pi asks which provider to use. Pi stores and refreshes the credential.

The tool is registered by default. If Pi has no openai-codex token, or if the ChatGPT account id cannot be found from the stored OAuth credential or decoded access token, the first codex_search call fails with an auth error that points back to /login openai-codex.

Set enabled: false if you want the extension installed but hidden for a project.

Tool

Default tool name:

codex_search

Example call:

{
  "name": "codex_search",
  "arguments": {
    "queries": ["latest OpenAI Codex release notes"],
    "search_context_size": "medium",
    "freshness": "live"
  }
}

Arguments:

• queries — required array of 1–5 search questions. Queries run in parallel; results are grouped by query.
• search_context_size — optional, one of low, medium, high; defaults to medium.
• freshness — optional, live or cached; defaults to live.

The tool returns text. When citations are available, the text includes a Sources: section.

The structured details object includes:

• model
• freshness / searchContextSize
• queryCount / failedQueryCount
• successes: per-query { query, text, citations, searchCalls, responseId?, usage? }
• failures: per-query { query, kind, message }

Failure kind is one of auth, rate_limit, transport, timeout, schema, or unknown.

Model used for search

The search request needs a Codex model id. The extension chooses it in this order:

1. model from env / project / home config, if set.
2. The active Pi model, if it comes from the openai-codex provider.
3. The default model from Codex's /codex/models response.

Most users do not need to set this.

Settings

Most users only need /login openai-codex. Use settings when you want to rename the tool, disable it for a project, pin a model, or change defaults.

Open the interactive settings dialog:

/codex-search-settings

Useful subcommands:

/codex-search-settings status
/codex-search-settings reset

Settings are merged from three layers, highest precedence first:

1. Environment variables.
2. Project file: <cwd>/.pi/pi-codex-search.json.
3. Home file: ~/.pi/pi-codex-search.json.

Each layer is optional. Missing files are skipped. Malformed JSON or invalid values fail fast so you do not silently run with the wrong tool settings.

Full schema, all fields optional:

{
  "enabled": true,
  "toolName": "codex_search",
  "model": "gpt-5-codex",
  "baseUrl": "https://chatgpt.com/backend-api",
  "clientVersion": "1.0.0",
  "searchContextSize": "medium",
  "freshness": "live"
}

enabled: false skips tool registration entirely. The model will not see codex_search at all.

toolName lets you avoid conflicts with another extension. Tool names must match [a-zA-Z_][a-zA-Z0-9_]{0,63}.

Environment variable equivalents:

Field	Env var
enabled	PI_CODEX_WEB_SEARCH_ENABLED
toolName	PI_CODEX_WEB_SEARCH_TOOL_NAME
model	PI_CODEX_WEB_SEARCH_MODEL
baseUrl	PI_CODEX_WEB_SEARCH_BASE_URL
clientVersion	PI_CODEX_WEB_SEARCH_CLIENT_VERSION
searchContextSize	PI_CODEX_WEB_SEARCH_CONTEXT_SIZE
freshness	PI_CODEX_WEB_SEARCH_FRESHNESS

PI_CODEX_WEB_SEARCH_ENABLED accepts true / false (case-insensitive). Any other value fails config loading.

Interactive edits write the selected config file immediately. When you close the dialog, Pi reloads so the new tool name and defaults apply without restarting the whole terminal.

Notes

Codex search vs model search

This does not add browsing to the model provider itself. It adds a Pi tool. The model decides when to call codex_search, just like any other tool.

Account id

Codex requests need both the access token and the ChatGPT account id. The extension first checks Pi's stored OAuth credential. If that does not include an account id, it tries to extract one from the access token.

Troubleshooting

codex_search fails with an auth error

Run:

/login openai-codex

If Pi asks for a provider, choose ChatGPT Plus/Pro (Codex Subscription). The extension picks up the refreshed credential on the next call.

codex_search says the account id was not found

The stored OAuth credential did not include an account id, and the extension could not decode one from the access token. Re-run /login openai-codex so Pi refreshes the credential.

The model does not see codex_search

Check whether enabled is false in env, project config, or home config:

/codex-search-settings status

Remember that env overrides project, and project overrides home.

Search uses the wrong model

Set model in your config file, or set PI_CODEX_WEB_SEARCH_MODEL, to the Codex model id you want. If unset, the extension uses the active Codex model when possible, then falls back to the default model from /codex/models.

A different extension already registers codex_search

Use /codex-search-settings to rename this extension's tool, or set toolName in ~/.pi/pi-codex-search.json. Tool renames apply after the settings dialog reloads Pi.

Development

npm install
npm run check
npm test
npm run lint
npm run format:check

Release

This repository follows the same release shape as pi-provider-kimi-code:

• release-naming.env defines PKG_NAME=pi-codex-search and TAG_PREFIX=v.
• scripts/next-version.sh computes the next semantic version from tags.
• .github/workflows/release-command.yml creates release commits and tags.
• .github/workflows/release-on-tag.yml publishes to npm with provenance and attaches pi-codex-search.tar.gz to the GitHub release.

References

• Pi: earendil-works/pi

License

MIT