🌉 Hermes Codex Router

The complete Hermes ↔ Codex integration bundle — Codex as a first-class Hermes tool, DeepSeek V4 Flash on the native Responses API, with bidirectional consult and cross-session context.

The stack at a glance

One picture, the whole architecture — every layer tested and verified end-to-end:

┌──────────────────────────────────────────────────────────────┐
│                  LAYER 1 · MAIN BRAIN                         │
│        Hermes Agent — memory, persona, orchestration          │
└──────────────────────────────────────────────────────────────┘
        │  main loop (Responses API)           ▲ reverse consult
        ▼                                      │ (two channels)
┌────────────────────────┐      ┌───────────────────────────────┐
│  LAYER 2 · MODEL       │      │  LAYER 3a · REVERSE CONSULT   │
│  deepseek-responses    │      │  codex-plus-hermes-team MCP   │
│  api_mode:             │      │  hermes_team_ask_agent ✅     │
│    codex_responses     │      │  auto-resume live session ✅  │
│  api.deepseek.com      │      │  model/provider pinned ✅     │
│  1M context · no VPN   │      └───────────────────────────────┘
└────────────────────────┘                   ▲
        │  dispatch                          │ mcp__hermes_team__*
        ▼                                    │
┌──────────────────────────────────────────────────────────────┐
│  LAYER 3b · EXECUTION TOOL (this repo)                       │
│  codex tool → Codex CLI 0.146+                               │
│  DeepSeek official models.json adapter                       │
│  apply_patch native · effort levels · no VPN                 │
└──────────────────────────────────────────────────────────────┘
        │  session artifacts
        ▼
┌──────────────────────────────────────────────────────────────┐
│  LAYER 4 · CONTEXT & FALLBACK BRIDGE                         │
│  Athena backend /hermes/ask (HTTP, any caller)               │
│  auto-resume live session · recall cache · memory read       │
│  standby role: L2 covers ask; Athena stays as fallback       │
└──────────────────────────────────────────────────────────────┘

简体中文版

┌────────────────────────────────────────────────────────────┐
│                       第 1 层 · 主脑                       │
│             Hermes Agent —— 记忆 · 人设 · 编排             │
└────────────────────────────────────────────────────────────┘
│  主循环（Responses API）       ▲ 反向咨询（双通道）
▼                               │
┌────────────────────────────┐  ┌────────────────────────────┐
│       第 2 层 · 模型       │  │    第 3a 层 · 反向咨询     │
│     deepseek-responses     │  │ codex-plus-hermes-team MCP │
│ api_mode: codex_responses  │  │ hermes_team_ask_agent ✅   │
│      api.deepseek.com      │  │ 自动 resume 当前会话 ✅    │
│     1M 上下文 · 免梯子     │  │ 模型/通道 pin 已修 ✅      │
└────────────────────────────┘  └────────────────────────────┘
│  派发                           ▲ mcp__hermes_team__*
▼                               │
┌────────────────────────────────────────────────────────────┐
│                第 3b 层 · 执行体（本仓库）                 │
│               codex 工具 → Codex CLI 0.146+                │
│               DeepSeek 官方 models.json 适配               │
│            apply_patch 原生 · 推理档位 · 免梯子            │
└────────────────────────────────────────────────────────────┘
│  会话产物
▼
┌────────────────────────────────────────────────────────────┐
│           第 4 层 · 上下文与兜底桥                          │
│        Athena 后端 /hermes/ask（HTTP，任意调用方）          │
│        自动 resume 当前会话 · recall 缓存 · 记忆读取        │
│        备用角色：L2 已覆盖 ask，Athena 降级为兜底           │
└────────────────────────────────────────────────────────────┘

The closed loop: Hermes thinks on the native Responses API → dispatches to Codex → Codex executes with DeepSeek's official adaptation → Codex consults Hermes back through two verified channels — native MCP (hermes_team_ask_agent, auto-resumes the live Hermes session) and the HTTP fallback (Athena /hermes/ask, any caller) → context survives sessions (resume, read-only).

What this is

This is not just a plugin — it is the assembled, tested recipe for the full Hermes ↔ Codex closed loop (see the diagram above):

Hermes thinks over DeepSeek's native Responses API (deepseek-responses provider, 1M context)
Hermes dispatches to Codex through the codex tool (this repo's plugin)
Codex executes with DeepSeek's official Codex adaptation (apply_patch, effort levels, multi-agent v2)
Codex consults Hermes back — native MCP (hermes_team_ask_agent, auto-resumes the live session) or HTTP fallback (Athena /hermes/ask)
Context survives sessions — both channels resume the live Hermes session read-only, so reverse-asks carry the real conversation, not a vacuum

See ARCHITECTURE.md for layer ownership details and INTEGRATION.md for the step-by-step assembly guide (every step verified on Windows 11).

Why this combination?

DeepSeek officially adapted V4 Flash for Codex (native Responses API, full models.json metadata, one-click setup) — no other agent CLI gets this depth.
api.deepseek.com is reachable directly from China — no VPN required.
Your API keys never touch disk: everything reads from env / Hermes .env.

Quick Start

Full stack takes ~10 minutes following INTEGRATION.md. Plugin-only is ~2 minutes if Codex + DeepSeek are already configured.

Step 0 — health check (recommended):

bash scripts/check-setup.sh   # ✅ all green → proceed; ❌ tells you exactly what's missing

# 1. Install the plugin into Hermes
# (ZIP downloads extract to <repo>-main/ — rename or adjust the path)
cp -r hermes-codex-loop /path/to/hermes/runtime-data/plugins/

# 2. Point Codex CLI at DeepSeek (official one-click script — choose deepseek-v4-flash)
#    Windows:  irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex
#    macOS/Linux: bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.sh)

# 2b. IMPORTANT — un-break MCP tool visibility (DeepSeek setup pitfall, openai/codex#36382):
#     The official setup writes supports_search_tool=true + tool_mode=null, which
#     silently hides ALL configured MCP tools in exec mode. Fix in ~/.codex/models.json:
#     set "supports_search_tool": false for every deepseek model. check-setup.sh [7/7]
#     detects the conflict automatically.

# 3. Make sure DEEPSEEK_API_KEY is visible to Hermes
export DEEPSEEK_API_KEY="sk-..."        # or put it in your Hermes .env

Restart Hermes. You now have a codex tool.

First smoke test — ask Hermes:

Use the codex tool to create a hello.py in a git repo and run it.

Expected: Hermes calls codex, Codex writes the file, runs it, and reports the real output.

For the full stack (native Responses API main loop + reverse consult + recall), follow INTEGRATION.md — it's the exact tested path.

Repository layout

hermes-codex-loop/
├── __init__.py                 # the plugin: `codex` tool + guidance + delegate injection
├── README.md                   # you are here
├── ARCHITECTURE.md             # four-layer closed-loop diagram
├── INTEGRATION.md              # step-by-step assembly (verified on Windows 11)
├── config/
│   ├── hermes-config.example.yaml   # deepseek-responses provider + Athena MCP blocks
│   ├── codex-config.example.toml    # ~/.codex/config.toml blocks (deepseek/zen/hermes-team)
│   └── team.example.yaml            # codex-plus-hermes-team team.yaml template
└── LICENSE

Usage

Tool schema

Parameter	Type	Default	Description
`task`	string	—	What to build/fix/refactor. Be specific: files, expected behavior, constraints.
`model`	`flash` \| `pro`	`flash`	`flash` → `deepseek-v4-flash`；`pro` → `deepseek-v4-pro`（暂不可用：官方 Codex 集成 2026 年 8 月初开放，当前返回 invalid_request_error）
`directory`	string	cwd	Working directory (should be a git repo)
`verify`	bool	`true`	Runs `git diff --stat` after execution

Example prompts

# Daily fix
codex(task="Fix the flaky test in tests/auth_test.py and make sure the suite passes",
      directory="/path/to/project")

# Complex architecture work
codex(task="Refactor the auth module into a plugin architecture with clear interfaces",
      model="pro",
      directory="/path/to/project")

# Skip verification for scratch work
codex(task="Scaffold a minimal FastAPI app", verify=false, directory="/tmp/scratch")

What you get back

{
  "status": "ok",
  "model": "deepseek-v4-flash",
  "output": "…real output from Codex…",
  "git_diff_stat": " auth.py | 12 ++++++++++++"
}

status is based on the real exit code — this plugin never fabricates results.

Orchestration rules

Codex is the primary coding executor — Hermes dispatches coding work to Codex instead of doing it inline. Three constraints + one boundary (inline one-line edits are allowed; everything else goes to Codex) are codified in AGENTS.md and enforced by the plugin's session guidance and delegate injection.

Reverse consult (bidirectional loop)

Two verified channels let Codex ask Hermes back — both carry the live conversation context (auto --resume of the most recent active session, read-only, no pollution):

	L2 · native MCP	L1 · HTTP fallback
How	`mcp__hermes_team__hermes_team_ask_agent`	`curl POST http://127.0.0.1:8390/hermes/ask`
Requires	`~/.codex/config.toml` hermes-team MCP + `startup_timeout_sec=120`	Athena backend running (Hermes venv python, PATH prefix)
Model pin	`team.yaml`: `model: deepseek-v4-flash`, `provider: deepseek`	built into hermes.py
Context	auto-resume live session	auto-resume live session (or explicit `session_id`)
Status	✅ verified (29s round trip, real answer)	✅ verified (15s round trip)
Role	primary channel	fallback / any non-codex caller (scripts, other agents)

Codex-side trigger — ~/.codex/AGENTS.md (global) defines when to reverse-ask: project conventions / user preferences / historical decisions missing and material to the task. Ask once, verbatim answer, never block on failure. Verified live: Codex asked a naming convention mid-task and followed Hermes's answer (count_by_extension).

MCP toolset status (10 tools):

Tool	Status	Notes
`hermes_team_ask_agent`	✅ verified	sync consult, ~15-30s
`hermes_team_health` / `list_agents` / `inspect_agent` / `discover_roles`	✅ present	diagnostics
`hermes_team_route` / `ask_panel`	⏸ single-profile	meaningful with 2+ Hermes profiles
`hermes_team_create_task` / `get_task` / `collect_result`	⏸ needs kanban	set `kanban.enabled: true` + Hermes kanban board

Configuration

All optional. Defaults work for the common Hermes layout.

Env var	Default	Purpose
`CODEX_BIN`	`D:/Agent/codex/node_modules/.bin/codex.cmd` → `codex` on PATH	Codex CLI binary path
`HERMES_HOME`	—	Hermes home dir (for `.env` discovery)
`HERMES_ENV_FILE`	—	Explicit path to an `.env` file holding `DEEPSEEK_API_KEY`

Key lookup order: DEEPSEEK_API_KEY env var → $HERMES_HOME/.env → ~/.hermes/.env → <cwd>/.env.

delegate_task integration: for coding goals, the plugin auto-injects Codex execution instructions into subagent context (marked with codex-injected to avoid double injection).

Troubleshooting

Symptom	Cause	Fix
`401 Unauthorized: Your api key: ****HERE> is invalid`	Codex sends the literal `experimental_bearer_token` placeholder from config.toml	Use `env_key = "DEEPSEEK_API_KEY"` instead of `experimental_bearer_token`
Codex writes nothing: "read-only sandbox" even with `--sandbox workspace-write`	Known bug on Windows (codex 0.145/0.146): workspace-write behaves read-only	This plugin already uses `--dangerously-bypass-approvals-and-sandbox` — keep it to trusted directories
Tool reports "codex CLI 未找到"	`CODEX_BIN` not set and Codex not on PATH	Set `CODEX_BIN` to your `codex.cmd`/`codex` path, or add Codex to PATH
Tool reports "缺少 DEEPSEEK_API_KEY"	Key not in env, Hermes `.env`, or `HERMES_ENV_FILE`	Export the key or add it to one of the `.env` candidates
Plugin loads but `codex` tool missing from the toolset	Hermes hasn't reloaded plugins	Restart the Hermes session
Athena MCP bridge returns 502 to backend	System proxy (Clash/v2rayN) hijacks localhost via httpx	Set `NO_PROXY=127.0.0.1,localhost` in the MCP server env
Athena backend: `ModuleNotFoundError: backend`	Running `backend/launcher.py` directly	Use `python -m backend.launcher` from the repo root
Athena `/hermes/ask` → 503 `WinError 2`	backend can't find `hermes` on its process PATH (Windows)	Prefix PATH with hermes.exe's dir when launching backend — see INTEGRATION.md
MCP tools silently missing in `codex exec` (hermes-team tools never appear)	DeepSeek official setup writes `supports_search_tool=true` + `tool_mode=null` in models.json — hides all MCP tools (openai/codex#36382)	Set `"supports_search_tool": false` for deepseek models in `~/.codex/models.json`; `check-setup.sh [7/7]` verifies
MCP server "was not ready" / tools appear intermittently	hermes-team server starts slower than codex's default MCP timeout	Add `startup_timeout_sec = 120` under `[mcp_servers.hermes-team]` in `~/.codex/config.toml`
Reverse-ask returns Zen `401 CreditsError`	hermes-team server didn't pin model/provider → profile falls back to a paid gateway model	`team.yaml`: `model: "deepseek-v4-flash"`, `provider: "deepseek"` (schema must include the fields — keep dist in sync with src if you build manually)

More traps (Windows build, npm registry, MSYS paths) in INTEGRATION.md.

⚠️ Third-party license note: this repo is MIT and contains no third-party source code. It only links to and configures upstream projects. Upstream licenses: hermes-agent / hermes-code-bridge / codex-plus-hermes-team are MIT. Athena declares no license (no LICENSE file as of 2026-08) — check its repo before depending on it for your own project.

Acknowledgements

The plugin is a thin, parameterized fork of patterns from; the bundle relies on:

deepseek-router — in-repo plugin pattern (register_tool + pre_session_init + pre_tool_call hooks)
hermes-code-bridge — Hermes-as-control-plane dispatch protocols
Athena — workspace orchestration, Hermes MCP bridge, recall
codex-plus-hermes-team — Codex consulting Hermes via MCP
NousResearch/hermes-agent — the platform this extends
DeepSeek official Codex integration (models.json, setup scripts)

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🌉 Hermes Codex Router

The stack at a glance

Table of Contents

What this is

Quick Start

Repository layout

Usage

Tool schema

Example prompts

What you get back

Orchestration rules

Reverse consult (bidirectional loop)

Configuration

Troubleshooting

Acknowledgements

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github/workflows		.github/workflows
config		config
scripts		scripts
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
INTEGRATION.md		INTEGRATION.md
LICENSE		LICENSE
README.md		README.md
__init__.py		__init__.py
plugin.yaml		plugin.yaml

Folders and files

Latest commit

History

Repository files navigation

🌉 Hermes Codex Router

The stack at a glance

Table of Contents

What this is

Quick Start

Repository layout

Usage

Tool schema

Example prompts

What you get back

Orchestration rules

Reverse consult (bidirectional loop)

Configuration

Troubleshooting

Acknowledgements

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages