Repository navigation
feat(messaging): coordinate Codex and Claude sessions across enrolled hosts #6478
Description
Area
Multiple areas
What are you trying to accomplish?
Coordinate existing Codex and Claude Code sessions across several machines running OpenCodex.
For example, a development agent should discover a remote build or reviewer agent, send it a task, receive its response, and request notification when it becomes idle. Agents should not need to manage credentials, construct SSH tunnels, or repeatedly rediscover sessions.
Operators should be able to configure connectivity and restrict individual sessions from the dashboard.
What prevents this today?
Native messaging has different capabilities and boundaries across the two harnesses. Claude's local session messaging works well and should remain available, but its remote messaging is not always available in provider-proxied sessions.
Cross-machine coordination requires separate helpers, manual routing and SSH configuration. Sender identity and reply routing can depend on model-generated prose. An agent may answer its user instead of replying to the requesting agent, or create unnecessary acknowledgement loops.
There is no shared OpenCodex session directory or dashboard control for these messaging connections.
What should OpenCodex do?
Provide an opt-in messaging capability with:
- A common
ocx messageinterface for existing Codex and Claude sessions, locally and on enrolled hosts. - Automatic sender identification, exact recipient selection, reply destinations and request/response correlation. Distinguish submission from processing; never automatically replay uncertain sends.
- A shared, bounded session directory per node, with freshness and completeness indicators, without reading conversations or starting sessions.
- Two exclusive configuration modes: individually enrolled peers, or centrally managed membership providing logical all-to-all connectivity over coordinator-owned SSH tunnels. Workers should not need SSH credentials for one another.
- Dashboard controls for membership, tunnel health and session-level send/receive isolation, enforced by OpenCodex rather than prompts.
- One-shot idle notifications registered on the target's owning node, using local live state rather than the coordinator's cached status.
- A managed
message-agentskill with concise reply guidance. Preserve foreign or user-edited skills and prefer permitted native local Claude messaging. - Claude-compatible sender attribution and permission-class handling where reliable evidence is available. Messaging must not grant escalation, bypass permission denials or manufacture delegated authority.
Isolation would cover OpenCodex-managed traffic, not native messaging that bypasses OpenCodex. Disabled installations should start no messaging listeners or timers.
Example usage or interface
Configure an individual peer:
ocx message enable
ocx message hosts add worker-a --ssh user@machine-aFrom an existing agent session:
ocx message sessions --all-hosts --json
ocx message send --host worker-a \
--thread THREAD_UUID \
--message "Please review the change and report your findings." --json
ocx message send --host worker-a \
--agent claude --session SESSION_UUID \
--message "Please run the build and report the result." --json
ocx message watch-idle --host worker-a \
--agent claude --session SESSION_UUID \
--timeout 3600 --jsonAlternatively, an operator configures a coordinator and workers through Dashboard → Agent messaging → Topology. Session rows expose independent send/receive block controls.
These commands illustrate the proposed interface, not functionality already released upstream.
Alternatives or workarounds
- Native Claude messaging remains preferable for supported local Claude-to-Claude communication.
- Standalone messaging skills and socket helpers work, but leave discovery, attribution, connectivity and lifecycle management fragmented.
- Manually maintained SSH pairs are possible but cumbersome for several machines.
- Public listeners or copied worker SSH credentials are unnecessary; coordinator-owned loopback tunnels provide a narrower operating model.
Additional context
For Codex, the local implementation wraps native codex queue delivery to the existing app-server; it does not start a second daemon. Local delivery uses its Unix socket. Remote delivery uses codex queue --remote ... --remote-auth-token-env ... through an SSH-forwarded, loopback-only OpenCodex bridge. The bridge validates the receiving node's bearer token before forwarding permitted discovery and queue calls. Each node has its own messaging token, separate from provider/account credentials, passed via an environment variable rather than command-line arguments. Compatible Codex builds are required. Queued means submitted, not processed or immediately steered.
A local implementation exists, including focused regression coverage and operational use. It still needs preparation against current upstream dev, broader validation and maintainer security review.
I would welcome feedback on whether this belongs in OpenCodex and on a staged contribution:
- Core messaging, attribution and managed skill.
- Shared discovery, topology, dashboard and isolation.
- Native Claude interoperability and idle notifications.
References:
- Codex app-server documentation, including remote transports and bearer authentication.
- Claude Code cross-session messaging.
- Claude socket transport reference.
Checks
- I searched existing issues and documentation.
- This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
- I removed secrets and personal data.
Activity
Ingwannu commentedon Oct 3, 2026
This is a substantive opt-in architecture proposal, not an existing bug fix or approval to ship the local implementation. I would keep the first contribution small and independently reviewable: exact local-session discovery plus caller-owned queued delivery/correlation, explicit uncertain outcomes, bounded lifecycle and disabled-path tests. Add remote enrollment/topology only after the owner accepts that boundary and the native contracts are pinned to tested runtime versions; defer dashboard controls and cross-harness permission/idle semantics to separate stages. In particular, please retain your distinction between submitted and processed, never replay an uncertain send, and do not describe OpenCodex isolation as covering native traffic that bypasses it. Any contribution still needs current-dev preparation, named offline regressions, owning structure/ADR documentation and the required independent review. I have not started messaging listeners, enrolled hosts or reviewed the unsubmitted local implementation.
phillipod commentedon Oct 3, 2026
Thanks—that staging makes sense. I’ll keep the broader implementation as a local experiment and scope the first proposed contribution to local-session discovery and caller-owned Codex queued delivery/correlation, with no remote enrollment, dashboard controls, cross-harness permission handling or idle notifications.
It will preserve submitted-versus-processed semantics, explicit uncertain outcomes and no automatic replay, with bounded lifecycle and disabled-path regressions. I’ll prepare it against current
dev, document ownership and the native contract/runtime versions exercised, and seek the required independent review.Would that local-only Codex boundary be suitable for a first draft PR, or would you prefer a short design/ADR for agreement before implementation preparation?
phillipod commentedon Oct 4, 2026
Progress update: the first scoped contribution is now open and ready for review in #6544.
It implements local-only Codex discovery and caller-owned queued messaging, preserving submitted-versus-processed semantics, explicit uncertain outcomes and no automatic replay. Local validation and pinned-native fixture tests passed; the full-suite resource exception is documented in the PR. CodeRabbit reviewed the current head without actionable findings. Maintainer review and required hosted CI remain outstanding.
I've also planned the next proposed slice locally: CLI-only remote Codex messaging with individual SSH peer enrollment, protected bearer credentials, an authenticated loopback bridge to the existing app-server, and bidirectional reply routes. It would reuse Remote Link’s SSH building blocks without changing its enrollment or provider-routing behavior.
The working lifecycle assumption is an explicitly invoked foreground owner for listeners and tunnels, leaving ordinary proxy startup unchanged. The first implementation step would pin authenticated native queue behavior in isolated fixtures before integrating enrollment and SSH.
Managed mesh configuration, dashboard/cache controls, isolation, Claude messaging, managed skills and idle notifications remain deferred.
This next scope remains provisional pending owner acceptance of the local boundary. Feedback on the resource lifetime or a preference for a smaller intermediate slice would be welcome.
Ingwannu commentedon Oct 4, 2026
Thanks for publishing the local-only slice as #6544. I have checked its ownership document and am doing a scoped offline lifecycle review; that does not yet approve the complete PR or a remote follow-on. Keeping listeners/tunnels under an explicitly invoked foreground owner is a reasonable proposal to document, but the remote slice should remain provisional until the owner accepts the boundary. Its design needs one aggregate budget across peers (not multiplied per tunnel), bounded pending requests/output, idempotent cancellation and TERM/KILL cleanup, and an explicit unknown outcome for a send whose helper already started. Keep ordinary startup inactive and do not turn reconnect into automatic resend. Remote enrollment/bearer/SSH and cross-harness semantics need separate accepted contracts and independent review; I have not enrolled hosts, opened tunnels or invoked real native messaging.
feat(messaging): add local Codex queued session messaging (#6544)
lidge-jun commentedon Oct 18, 2026
Remote Codex messaging over SSH landed on dev via #6891 (merge commit 8640c2f): enrolled hosts with pinned keys, receiver-bound origin, outbound-only enrollment by default with explicit allow-inbound, inert until
ocx message enableon both nodes. Claude sessions, mesh coordination, dashboard and idle notifications from this issue remain open.lidge-jun commentedon Oct 22, 2026
Local Codex queued session messaging (#6544) and enrolled-host remote messaging have shipped. Please open a focused issue for any cross-host coordination gap that remains.