Skip to main content

What is ContextRelay

ContextRelay is a local control-plane that coordinates two trusted agent processes - Claude Code (Anthropic) and Codex (OpenAI) - as one auditable coding team on a single workstation. It runs entirely on your machine over loopback: it does not run in the cloud, and it does not isolate the two agents from each other. Instead, it wires them together through a shared daemon and a durable, append-only ledger so they can exchange messages, hand off work, debate decisions, and leave a record you can audit before you ship.

ContextRelay is provider-neutral. Claude Code and Codex are separate vendor products; neither one orchestrates the other. ContextRelay is the neutral layer between them - one repository, one git owner, one human-in-the-loop policy, and one shared record of everything the agents did.

Not a sandbox

ContextRelay is local developer tooling, not a hosted service and not a security boundary between tools you do not trust. It connects two agents you already run and trust; it does not sandbox them from each other. For where the real trust boundaries are, see Trust boundaries and threat model.

This page is a conceptual map. It names every moving part you will keep meeting in the rest of the docs, so later pages can assume the vocabulary. It does not cover installation - head to Install and first run when you are ready to set up.

The parts you will keep meeting​

ContextRelay is a handful of cooperating pieces. Learn these names once and the rest of the docs read easily.

PartOne-line definition
DaemonThe loopback-only control server at the center of each project. It owns the ledger, routes messages between Claude and Codex, and enforces policy (permissions, coordinator, autonomy).
BridgeThe Claude Code MCP plugin process. It connects Claude to the daemon over a local WebSocket and is what turns Claude's tool calls into ledger writes and live messages to Codex.
LedgerThe append-only JSONL log of shared context under .contextrelay/state/. Every message, handoff, note, artifact, and decision is recorded here. It is the single source of truth for recovery, audit, and finality.
CoordinatorThe one agent that owns git writes (branch, commit, merge, push, PR). Configured in .contextrelay/config.json; the other agent uses read-only git and hands git work to the coordinator.
MCP toolsHow each agent talks to the other through the daemon - handoff, reply, deliberate_with_codex/deliberate_with_claude, append_note, read_context, and more.
Native TUIThe terminal dashboard. Run ctxrelay (or contextrelay / context-relay) with no subcommand to see daemon health, agent states, the queue, handoffs, and launch controls.
ViewerThe read-only browser Command Deck (ctxrelay viewer) for task lanes, artifacts, policy, status, and timeline inspection.
SessionsA default runtime pair (Claude foreground + Codex) on the project root, plus optional named sessions that can bind to separate git worktrees for review or debugging lanes.
Three names, one CLI

contextrelay, ctxrelay, and context-relay are interchangeable - they all point at the same CLI from the @proofofwork-agency/contextrelay package. This page uses the short ctxrelay form.

How the pieces fit together​

Here is the data flow in words - no installation required to understand it.

  1. Both agents connect to the daemon over loopback. Claude's plugin (the bridge) connects to the daemon via a local WebSocket. Codex connects through ContextRelay's MCP registration and app-server proxy. Neither agent talks to the other directly; the daemon sits in the middle.

  2. Everything durable goes to the ledger. When Claude hands off a task, Codex replies, either agent records a note or an artifact, or a finality decision is made, the daemon appends an entry to the JSONL ledger under .contextrelay/state/. Nothing important happens "off the record."

  3. Agents pull shared context from the ledger. Each agent calls read_context to fetch recent ledger entries and the latest still-open handoff. That is how Codex sees what Claude decided, and vice versa, even though they are separate processes.

  4. The daemon enforces policy on every write. It checks the coordinator role before git-sensitive work, applies the permission model, and keeps read-only-by-default safety in force. The agents propose; the daemon and the human dispose.

You inspect all of this through the native TUI (live dashboard) or the viewer (browser Command Deck). Both are read-and-control surfaces for you - they are not how the agents talk to each other.

Agents cannot read each other's minds

Claude and Codex are independent processes. They cannot see each other's hidden reasoning - only what is written into bridge messages and the ledger. This is the single most important habit in ContextRelay: when you hand off or reply, write the useful context down - the goal, the current plan, files touched, blockers, decisions, and the next step. Anything left unsaid is invisible to the other agent. The rest of these docs return to this point often.

Why a control-plane and not just "two chat windows"​

Running Claude and Codex in two terminals by hand gives you copy-paste and no memory. ContextRelay adds the parts that make a team rather than two strangers:

  • One shared, durable record so work survives a crash and can be audited - see The shared durable ledger.
  • One git owner so two agents never race to write the same branch - see Coordinator and git-write policy.
  • Read-only by default, with autonomous edits (act:write) and read-only backup agents both off until you explicitly enable them behind layered gates - see Read-only by default.
  • Activation you control: ContextRelay ships auto-connect on, but you can make it dormant-by-default per user and opt individual sessions back in - see Activation: auto-connect vs dormant.

Next steps​