d6eb78dcee
codex-channel-molecule is the codex-side counterpart to hermes-channel-molecule. It long-polls the molecule platform inbox via molecule_runtime.a2a_tools.tool_wait_for_message, runs `codex exec --resume <session>` per inbound message, captures the assistant reply from stdout, and routes it back through send_message_to_user (canvas chat) or delegate_task (peer agent), then acks the inbox row. Per chat thread (one canvas-user thread or one peer-workspace thread) gets its own codex session_id, persisted to disk so daemon restarts keep conversation context. Reply-routing failures skip the inbox_pop ack so the platform's at-least-once delivery re-surfaces the row on the next poll. This daemon is the operator-unblock until openai/codex#17543 lands — once codex itself accepts MCP custom notifications as Op::UserInput through the wired-in MCP server, this daemon becomes redundant. The README's deprecation-path section calls that out so future operators know when to switch off. Tests cover the dispatch loop with fake tools (8 tests asserting exact contracts: canvas vs peer routing, session continuity, persistence across restarts, timeout sentinel handling, at-least-once on reply failure, exit-code surfacing, A2A multipart text). The codex_runner tests are real-subprocess (fake codex script spawned via asyncio.create_subprocess_exec) so the boot path matches production — no in-process mocking of the spawn boundary. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .github/workflows | ||
| codex_channel_molecule | ||
| tests | ||
| .gitignore | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
codex-channel-molecule
Bridge daemon — gives codex CLI push parity with the Molecule AI platform's other external runtimes.
The Molecule platform's hermes-channel-molecule plugin gives hermes-agent true push delivery — peer agents and canvas-user messages land mid-session as conversation turns. Codex CLI has no plugin API today and its MCP runtime drops inbound notifications, so this daemon is the equivalent push surface — built outside the codex process.
How it works
canvas user / peer agent ──► molecule platform inbox
│
wait_for_message (long-poll)
│
▼
codex-channel-molecule daemon
│
codex exec --resume <sid> "<msg>"
│
capture stdout
│
send_message_to_user / delegate_task
│
inbox_pop(activity_id)
│
▼
canvas chat / peer workspace
Per chat thread (one canvas-user thread or one peer-workspace thread) gets its own codex session_id, persisted to ~/.codex-channel-molecule/sessions.json so daemon restarts don't lose conversation context.
When to use this vs. the codex tab in the External Connect modal
The codex tab wires the molecule MCP server into ~/.codex/config.toml so codex can call platform tools (list_peers, delegate_task, send_message_to_user, commit_memory, etc.). That's outbound — codex calls out to the platform.
This daemon is the inbound counterpart — the platform pushes to codex. Run both for full bidirectional integration.
Install
npm install -g @openai/codex@^0.57
pip install codex-channel-molecule
Configure + run
The same env-var contract as hermes-channel-molecule's outbound MCP path (WORKSPACE_ID, PLATFORM_URL, MOLECULE_WORKSPACE_TOKEN):
export WORKSPACE_ID=<uuid from External Connect modal>
export PLATFORM_URL=https://<your-tenant>.moleculesai.app
export MOLECULE_WORKSPACE_TOKEN=<bearer token from External Connect modal>
codex-channel-molecule
The daemon runs in the foreground; logs go to stderr. For systemd hosts, register a unit; for one-off use, nohup ... & plus a log file works.
Deprecation path
When openai/codex#17543 lands upstream — a generic path for handling MCP custom notifications in codex and forwarding them into the active session as user submissions — this daemon becomes redundant. Codex itself will accept inbound molecule messages as Op::UserInput directly through the MCP server already wired in ~/.codex/config.toml. Until then, this is the operator-facing answer.
Development
git clone https://github.com/Molecule-AI/codex-channel-molecule
cd codex-channel-molecule
pip install -e ".[test]"
pytest -q
Tests are entirely real-subprocess (no mocking the spawn boundary) so the boot path is covered the same way the daemon runs in production.
License
Apache-2.0