Codex Search & Extract for Hermes Agent

A web search + content extraction backend for Hermes Agent powered by OpenAI Codex's standalone web-retrieval endpoint — zero GPT inference tokens. Search is pure retrieval; the active Hermes model receives the raw results and does all the reasoning.

Works with any model configured in Hermes. No API key: it reuses your existing codex login session (~/.codex/auth.json).

Upstream proposal: this backend is being contributed to Hermes Agent in NousResearch/hermes-agent#82717. Until it merges (or if it never does), this repo is the canonical distribution.

Features

• web_search — structured results (title, URL, snippet) with OpenAI-quality ranking
• web_extract — opens any URL and returns clean page text (the URL itself works as the reference id — no prior search needed)
• Any model — the backend is model-agnostic; only the retrieval happens on Codex's side
• Privacy — only the query/URL is sent to the retrieval service; never conversation history, code, or system prompt

Requirements

• Hermes Agent with user-plugin support (~/.hermes/plugins/)
• A valid Codex session: codex login (creates ~/.codex/auth.json) or CODEX_ACCESS_TOKEN (+ optional CODEX_ACCOUNT_ID) in your .env

Install

Hermes installs plugins from Git repos natively — no manual cloning or symlinks:

hermes plugins install lgwacker/codex-search-hermes/plugins/web/codex --enable

Then select it as the web backend (skip this if you already use another backend on purpose):

hermes config set web.backend codex   # search + extract

Start a new Hermes session, then verify:

hermes plugins list            # → web-codex enabled
hermes config get web.backend  # → codex

Updating:

hermes plugins update web-codex

Removing:

hermes plugins remove web-codex

Configuration

# ~/.hermes/config.yaml
web:
  backend: codex          # shared fallback (search + extract)
  # search_backend: codex  # per-capability override (optional)
  # extract_backend: codex # per-capability override (optional)

Credential precedence (mirrors the original plugin):

1. CODEX_ACCESS_TOKEN (+ CODEX_ACCOUNT_ID)
2. ~/.codex/auth.json → tokens.access_token / tokens.account_id

Expired token (HTTP 401/403)? Re-run codex login.

How it works

Hermes agent
  └─ web_search(query)          POST /backend-api/codex/alpha/search
  │                              commands: {search_query: [{q}]}
  │                              → structured results (title, url, snippet)
  └─ web_extract(url)           POST /backend-api/codex/alpha/search
                                 commands: {open: [{ref_id: <url>}], response_length: "long"}
                                 → page text (citation markers / line numbers stripped)

Payload: {id: <session>, model: "gpt-4o", commands: {...}} — the model field selects the retrieval contract; not an inference call.

Testing

The test suite is the upstream one (real imports, only httpx.post faked). Run it standalone:

uv run pytest tests/ -q        # provider logic; registry tests auto-skip

For the full suite (including plugin-registry registration), run inside a Hermes checkout — see .github/workflows/test.yml for the exact recipe CI uses.

Warnings

• Undocumented endpoint: alpha path on ChatGPT's backend, reverse-engineered. It can change, rate-limit, or break without notice. Hermes falls back to another backend if codex becomes unavailable.
• Terms of use: your own Codex OAuth token against a private endpoint. Low risk (indistinguishable from normal Codex CLI usage), but it exists — you're responsible for your OpenAI account.
• Not affiliated with OpenAI. The Codex CLI is the official client; this project is independent.

Development

The plugin lives at plugins/web/codex/ — the layout bundled Hermes backends use. For local iteration, symlink it into your Hermes plugins dir:

ln -s "$(pwd)/plugins/web/codex" ~/.hermes/plugins/web/codex
hermes plugins enable web/codex

Credits

• codex-search-opencode (MIT) by mateusdcc — original reverse-engineering of the endpoint
• Hermes Agent — the plugin system this backend plugs into

License

MIT — see LICENSE.