codex-hermes-bridge

codex-hermes-bridge is an MCP bridge that lets a Codex custom agent delegate bounded tasks to Hermes Agent through the Hermes Runs API.

It exposes Hermes as tools, not as a Codex model provider. Codex remains the coordinator; Hermes runs the delegated task and sends status, event summaries, and final output back through MCP.

Install

npm install -g codex-hermes-bridge
codex-hermes-bridge install

Until the package is published to npm, install from source:

git clone https://github.com/myc0576/codex-hermes-bridge.git
cd codex-hermes-bridge
npm ci
npm run build
npm install -g .
codex-hermes-bridge install

For local development:

npm install
npm run build
node dist/cli.js install --command codex-hermes-bridge --dry-run

Tools

• hermes_delegate: start a Hermes run, wait for completion, summarize events, and return the result.
• hermes_start_run: start a run and return immediately.
• hermes_get_run: fetch pollable run status.
• hermes_get_events: consume and summarize the SSE event stream.
• hermes_stop_run: request interruption of a running task.
• hermes_health: check bridge config, Hermes CLI availability, API health, auth, and cwd policy.

Security Defaults

The bridge defaults to 127.0.0.1 and a generated local API key stored under ~/.codex-hermes-bridge/config.json. That default is intentionally scoped to one machine and one network namespace. If Codex and Hermes are split across Docker, WSL, SSH, a devcontainer, CI, or another remote boundary, set HERMES_API_BASE_URL explicitly.

Do not expose the Hermes API server on 0.0.0.0 without a strong API_SERVER_KEY. The bridge never prints the full generated key. 0.0.0.0 is a server bind address, not a client base URL. If you need IPv6 loopback, use HERMES_API_BASE_URL=http://[::1]:8642 and set HERMES_API_BIND_HOST=::1 for bridge-owned auto-starts.

Gateway auto-start is opt-in. hermes gateway run starts the full Hermes gateway for the active Hermes profile, so it can also activate configured messaging platforms and cron jobs. Prefer starting a dedicated Hermes API process yourself, or set HERMES_BRIDGE_AUTO_START=true only after checking that gateway side effects are acceptable.

CWD Policy

Hermes Runs API currently has no per-run cwd field. This bridge therefore refuses to guess.

• If the bridge starts Hermes, it injects TERMINAL_CWD=<requested cwd> and disables embedded kanban dispatch with HERMES_KANBAN_DISPATCH_IN_GATEWAY=false.
• If Hermes API is already running and the bridge cannot verify that it owns the gateway or that the gateway cwd matches, the tool returns an actionable error.

Environment Overrides

• HERMES_API_BASE_URL
• HERMES_API_KEY
• HERMES_API_BIND_HOST (default 127.0.0.1; used only when the bridge auto-starts Hermes)
• HERMES_BRIDGE_PORT
• HERMES_BRIDGE_AUTO_START=true
• CODEX_HERMES_BRIDGE_HOME

Development

npm install
npm test
npm run typecheck
npm run build