codex-search-opencode

Model-independent web search and multi-step web research for OpenCode, powered by the OpenAI Codex standalone search service.

codex-search-opencode gives an OpenCode agent two collision-resistant tools that retrieve live web results with zero GPT/Codex model inference turns and zero GPT tokens consumed by the search itself. It uses the Codex session already available on the machine through codex login or CODEX_ACCESS_TOKEN.

Tools

| Tool | Use | | --- | --- | | codex_search | A focused, single-query lookup. | | codex_web | Multi-step research with search_query, open, find, click, and response_length. |

The names are deliberately namespaced. They avoid replacing OpenCode built-ins or third-party tools such as web, web_search, and bash.

Requirements

• OpenCode 1.17 or later
• Bun, installed with OpenCode
• A valid Codex session from codex login, or CODEX_ACCESS_TOKEN and optionally CODEX_ACCOUNT_ID
• An OpenCode model with tool calling support

Install

From a local checkout

mkdir -p .opencode/plugins
cp /path/to/codex-search-opencode/.opencode/plugins/codex-search.ts .opencode/plugins/

The included project plugin re-exports src/index.ts. OpenCode discovers project plugins at startup.

From npm

After publishing, add the package to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["codex-search-opencode"]
}

OpenCode installs configured npm plugins with Bun when it starts.

Configure OpenCode with GPT-5.6 Luna

OpenCode's native OpenAI provider supplies openai/gpt-5.6-luna after ChatGPT Plus or Pro authentication. Authenticate once:

opencode providers login --provider openai

Choose ChatGPT Plus/Pro in the interactive prompt, complete the browser authorization, then set this project model in opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/gpt-5.6-luna"
}

Verify the provider and model:

opencode providers list
opencode models openai
opencode run --model openai/gpt-5.6-luna "Reply exactly: LUNA_OK"

If your installed OpenCode release reports that Luna is unavailable, upgrade OpenCode before retrying. The plugin itself does not depend on the agent model.

Use

Ask OpenCode to call a tool explicitly when testing:

Use codex_search to find the current OpenCode release.

For sourced, iterative research:

Use codex_web to research the latest Rust release. Search official sources, open the best result, verify the version, and include a Sources section.

codex_web accepts these arguments:

{
  "search_query": [{ "q": "OpenAI Codex GitHub repository", "domains": ["github.com"] }],
  "response_length": "medium"
}

Use returned reference IDs in later calls:

{ "open": [{ "ref_id": "turn0search0" }] }

{ "find": [{ "ref_id": "turn1view0", "pattern": "terminal" }] }

Authentication

The provider resolves credentials in this order:

1. CODEX_ACCESS_TOKEN and optional CODEX_ACCOUNT_ID
2. ~/.codex/auth.json, created by codex login

An optional project .env can define the same variables. Never commit it. See .env.example.

Commands

The checkout includes .opencode/commands/gpt-search.md, which registers /gpt-search for local use. For an npm installation, copy templates/gpt-search.md to .opencode/commands/gpt-search.md. Run it in OpenCode as follows:

/gpt-search latest Rust release

OpenCode custom commands are prompt templates, not direct plugin handlers. The active agent still invokes codex_search, but the search operation itself remains Zero-GPT.

Development

npm install
npm run typecheck
npm test

The default test suite covers command validation, response normalization and formatting, authentication errors, provider behavior, session continuity, tool schemas, adapter delegation, failure results, and live Codex search behavior.

The OpenCode agent end-to-end test is opt-in because it spends your OpenCode model quota:

RUN_OPENCODE_E2E=1 npm run test:opencode

It requires an authenticated OpenAI provider, access to openai/gpt-5.6-luna, and the local plugin shim in .opencode/plugins/.

Architecture

OpenCode agent
  ├─ codex_search(query)
  │    └─ Codex standalone search endpoint
  └─ codex_web(commands)
       └─ search, open, find, and click within one isolated session

See HOW-IT-WORKS.md for the implementation data flow and HOW-IT-WAS-EXTRACT.md for endpoint discovery notes.

Security and privacy

• Only the tool command is sent to the standalone search service by default.
• Research-page text is untrusted data. Do not follow instructions from retrieved pages.
• The plugin does not send repository files, system prompts, or conversation history to the service.
• Do not commit .env or Codex credential files.

License

MIT