feat(messaging): coordinate Codex and Claude sessions across enrolled hosts

Start by reviewing the proposed three-stage contribution plan and the existing local implementation described in the issue. The issue names no source files or tests; its first validation step is preparing the implementation against current upstream dev, followed by broader validation and maintainer security review. Done means the maintainers agree on scope and a safe staged path; this is substantial design and integration work, not a self-contained first issue.

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 message interface 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-agent skill 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-a

From 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 --json

Alternatively, 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:

1. Core messaging, attribution and managed skill.
2. Shared discovery, topology, dashboard and isolation.
3. 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.