Codex Hermes A2A Bridge

A local bridge so Codex can be the “front desk”: Codex calls MCP tools over stdio, the bridge turns requests into A2A v1.0/JSON-RPC to the Hermes profile default, then keeps conversation/task mapping in SQLite. Hermes remains the “brain” that runs the agent loop, memory, skills, tools, and internal orchestration.

Current version: v0.1.1. Only loopback endpoints are bound/called; there are no tools for model switching, plugins, configuration, updates, a shell, or controlling the Hermes service.

Independent project: this is independent community software, not an official product, not sponsored, and not representative of Nous Research/Hermes Agent or OpenAI/Codex. Brand names are used only to describe interoperability.

Architecture

Codex client --MCP stdio--> MCP server --> bridge core --> Hermes A2A :9900
                                      \--> SQLite context/task mapping

• Python 3.11 and a dedicated venv, not Hermes' venv.

• Official Python MCP SDK, httpx async, Pydantic, and SQLite stdlib.

• Each conversation_key opens a map entry to a Hermes contextId; subsequent turns reuse that mapping.

• Original prompts are not persisted; the bridge stores fingerprint, route, state, result, and minimal errors.

Related MCP server: ccg-mcp

Requirements and quick setup

• Python 3.11.

• Hermes Agent 0.20.5 with the A2A gateway running on loopback.

• A Codex client with MCP stdio support.

cd /absolute/path/to/codex-hermes-a2a-bridge
python3.11 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/codex-hermes-a2a-bridge doctor

Contributors can install additional testing tools with python -m pip install -e '.[dev]'. See .env.example for overrides; do not commit a real .env file.

Safe default configuration:

Enabling Hermes A2A and registering Codex

On initially installed Hermes 0.20.5:

hermes plugins enable a2a-platform --no-allow-tool-override
hermes config set gateway.platforms.a2a.enabled true
hermes gateway run --no-supervise

When the foreground process, a user service can be installed (no sudo):

hermes gateway install --start-now --start-on-login

Register the bridge in Codex shared MCP config:

codex mcp add codex-hermes-a2a-bridge -- \
  /absolute/path/to/codex-hermes-a2a-bridge/.venv/bin/codex-hermes-a2a-bridge serve
codex mcp get codex-hermes-a2a-bridge

A new Codex client must be opened/restarted to pick up the fresh entry. MCP stdio writes only protocol frames to stdout; diagnostics go to stderr.

Seven MCP tools in v0.1

The set of four MCP operations originally described in the study (discover, send, get, continue) is not full A2A. v0.1 folds these into seven high-level tools for conversation/task work; lower-level A2A operations such as push-notification CRUD and Hermes administration are not expё.

Example workflow

1. Codex calls OM hermes_status.

2. Codex calls hermes_chat(message=..., conversation_key=<stable>, mode="auto").

3. If the task is still running, use hermes_task_wait or hermes_task_get; do not blindly resend after an ambiguous timeout.

4. If neds_input=true, ask the user, then call hermes_chat with your conversation_key / context_id.

5. The next conversation line continues with the same mapp; hermes_contexts(action="close") only closes the bridge mapping.

For tasks with side effects, provide an idempotency_key. Hermes 0.20.5 does not have wire-level idempotency, so the bridge will not retry mutation sends when the result transport is unclear.

From v0.1.1, all three modes use SendStreamingMessage to get the A2A task ID from the very first event. sync still waits inline up to 30 seconds (or timeout whenever set lower); the stream remains alive until correlation timeout. For older records in outcome_unknown that lack an A2A ID, hermes_task_get / hermes_task_wait first try ListTasks(contextId) and then read Hermes' official conversation persistence. Recovery attaches a result only when there is exactly one local unresolved task and exactly one remote/disk candidate; ambiguous cases remain unchanged, with no resdend and no guessing. The disk fallback has no A2A state, so it issues a warning and treats an already persisted agent reply as completed.

Testing and operations

.venv/bin/pytest --cov=codex_hermes_a2a_bridge --cov-report=term-missing
.venv/bin/codex-hermes-a2a-bridge doctor
.venv/bin/codex-hermes-a2a-bridge smoke \
  'Reply with exactly MY_MARKER and nothing else.' \
  --conversation-key manual-smoke
.venv/bin/python scripts/live_check.py manual-smoke

Clock pytest uses a fake A2A server on an ephemeral loopback port and does not require a real Hermes. doctor and live_check.py are read-only. A smoke command sends a real task; run it only actively with g harmless content.

Security and privacy

• v0.1.1 rejects endpoints and Agent Card URLs that are not loopback, does not follow redirects, and does not accept tokens through MCP tool arguments.

• SQLite is stored by default outside the source tree with mode 0600; it holds mapping, fingerprint, state, result/artifact and minimal errors. Results can contain sensitive data, so apply an appropriate retention/change &backup policy.

• Original prompts are not persisted by bridge; Hermes may still write its own conversation / audit log. Fallback recovery only reads from the configured Hermes conversation store.

• The MCP server must be run by a trusted user; the seven tools can trigger Hermes, and Hermes may use skills / tools with side effects. Use an idempotency_key and do not resnd blindly when in outcome_unknown.

• Report vulnerabilities via [SECURITY.MD]. Do not post tokens, transcripts, or SQLite in issues.

Guarantees and upstream guarantees

The bridge guarantees a loopback policy, a durable local mapping, no retried sent send after ambiguity, and honest cancel semantics. The bridge does not guarantee that HProc Hermes will stop computation, that token‑level streaming is implemented, that wire‑level idempotency exists, or that tasks survive a Hermes restart.

Hermes 0.20.5 uses an in‑memory TaskStore, lifecycle SSE and protocol cancel does not abort the current turn. The bridge's conversation‑store recovery is a read‑only fallback, not a substitute for the upstream's durable task store. Verified details are in the Hermes A2A reference.

Troubleshooting

• a2a_unreachable: run hermes gateway status, check the card at http://127.0.1:9900/.well-known/agent-card.json.

• A2A plugin enabled but no port: check hermes config get gateway.platforms.a2a.enabled, then restart the gateway.

• Codex doesn't Pages or lists not present: run codex mcp get codex-herMes-a2a-bridge, then use a new Codex process/client.

• outcome_unknown: call hermes_task_get/`hermes; if still ambiguous, do not resend a task with side effects; ask user.

• turn_budget_exeeded: close the map and create a new conversation; do not reset budget/changes just to let the agent loop on forever.

• Hermes 0.20.5 loses the A2A TaskStore on restart; bridge keeps local task/result but remote refresh may say the task no longer exists.

• On macOS currently theif launchctl bootstrap returns exit 5, Hermes uses detached fallback: it works but does not auto-start/auto-restart. Use hermes gateway status to confirm.

Rollback

See scripts/rollback.sh. The script defaults to only printing the plan. scripts/rollback.sh --apply strips the exact MCP entry and the A2A configuration/plugin, but keeps the gateway service because the service may serve another platform. Only add --include-gateway-service if a gateway is installed solely for this rollout. Source, .venv, SQLite, and Hermes transcripts remain in place.

Scoped backups are created next to the config file and suffixed with .pre-codex-hermes-a2a-bridge-v0.1.bak; no full automatic restore is done, because it could overwrite fresh user changes.

Documentation

• v0.1 Implementation Plan

• v0.1 Testing Report

• Hermes A2A Reference v1.0

• MCP Bridge Design

• CHANGELOG

• Contributing Guide

• Security Policy

• Apache License 2.0

Canonical sources: OpenAI Codex MCP, Hermes A2A guide,, NousResearch/hermes-agent. Where they differ, the local Hermes 0.20.5 commit d5a... is authoritative.