Skip to main content

ContextRelay: two agents, one auditable session

Run Claude Code (Anthropic) and Codex (OpenAI) as one auditable coding team on a single workstation.

ContextRelay is a local, provider-neutral coordination control-plane. It wires Claude Code and Codex into the same repository through a loopback daemon, so they exchange live messages, hand off work, and debate decisions - with every message, handoff, note, artifact, and decision written to a shared, append-only ledger. You get a pair that reviews its own work, second opinions on risky calls, and a durable record of what the agents did before you ship. A native terminal dashboard and a browser viewer let you watch and steer the whole session.

Reach for ContextRelay when one agent should implement while the other reviews, when a risky decision needs a second opinion, or when you want an auditable record of what the agents did before you ship.

Current version

These docs describe ContextRelay 3.3.0, the current release on npm. After upgrading the package, run ctxrelay upgrade to reconcile your local setup.

Install and first run​

You need three things on your PATH first: Bun (v1.0+), Claude Code (v2.1.80+), and the Codex CLI. Bun is required because the daemon and the Claude plugin server run on Bun.

npm install -g @proofofwork-agency/contextrelay
ctxrelay init --instructions project
ctxrelay codex-mcp install
contextrelay

That sequence:

  • creates .contextrelay/config.json for this project;
  • installs the Claude Code plugin so Claude gets ContextRelay's MCP tools;
  • writes managed ContextRelay guidance into this repo's CLAUDE.md and AGENTS.md;
  • registers the ContextRelay MCP server with Codex so Codex gets its tools;
  • opens the native terminal dashboard.

Then start both agents and watch them in the control deck:

ctxrelay pair      # launch Claude + Codex in separate terminals, keep the TUI open

Or launch each side yourself:

ctxrelay claude    # start Claude Code wired into the daemon
ctxrelay codex     # start the Codex TUI wired into the daemon
Three names, one CLI

contextrelay, ctxrelay, and context-relay are the same binary - use whichever you prefer. This site uses ctxrelay for brevity.

Confirm everything is wired up, then stop the project's daemon when you're done:

ctxrelay doctor    # diagnose binaries, auth, state, plugin registration, daemon health
ctxrelay status    # daemon, session, connection, ledger, and policy state
ctxrelay kill      # stop this project's daemon and Codex runtime

Current lifecycle commands​

These are the two commands to know after first setup:

CommandWhen to use it
ctxrelay upgradeRun after npm install -g @proofofwork-agency/contextrelay@latest to reconcile config defaults, managed instruction blocks, the bare /contextrelay command, the Claude plugin, and any existing Codex MCP registration with the package now on disk.
ctxrelay standalone onMake ContextRelay not start automatically in every new session. It switches your baseline to dormant-by-default, slims always-on instruction blocks, and installs /contextrelay so you can opt a single session back in when you want the pair.

By default, ContextRelay is auto-connect ON: new sessions surface the hooks and collaboration guidance automatically. If you installed it globally but only want it sometimes, run ctxrelay standalone on; later use /contextrelay or ctxrelay attach to activate one workspace.

What you can do with it​

Each scenario below maps to a tutorial or concept - follow the link to go deeper.

  • Pair on a build. Claude and Codex work the same repository at once, exchanging live messages instead of you copy-pasting between two windows. → Your first paired session
  • Delegate implementation to Codex. Record a structured handoff with a reason, a concrete ask, and the relevant files; the other agent picks it up and reports back. → Delegate an implementation to Codex via handoff
  • Get a second opinion before a risky change. Hand the diff to the other agent for a severity-ordered risk review, or run a bounded deliberation to converge on a plan. → Run a risk-review before a big change
  • Run a single tool, opt the pair in only when you want it. Make ContextRelay dormant-by-default, then activate it for one session with /contextrelay (or ctxrelay attach). → Go dormant, then opt a session back in
  • Upgrade without resetting your choices. ctxrelay upgrade updates the managed surfaces after an npm update while preserving coordinator, permissions, and auto-connect vs dormant state. → Upgrade ContextRelay safely
  • Recover after a crash. The ledger is the source of truth: ctxrelay recover summarizes interrupted work, recent failures, and a resume prompt. → Troubleshooting and recovery
  • Gate a release. ctxrelay release-gate runs your build/check and records the evidence as a durable artifact for human sign-off. → Finality and human sign-off

What makes it different​

Native Claude Code Workflows orchestrate Claude sub-agents within one Claude session. ContextRelay solves a different problem: it coordinates two separate products - Claude Code and Codex - as one team. Neither product orchestrates the other; ContextRelay orchestrates both as separate trusted processes around a single project daemon.

That makes it the governance and audit layer for the work:

  • One repository, one git owner. A configured coordinator (Claude, Codex, or the human) owns git writes - branch, commit, merge, push, PR. Non-coordinator agents stay read-only on git and hand off git-sensitive work. This avoids dual-write races. → Coordinator and git-write policy
  • One shared record. Every message, handoff, note, artifact, and decision lands in one local JSONL ledger - the single source of authority for recovery, audit, and finality. Agents can't see each other's hidden reasoning, only what's written down. → The shared durable ledger
  • One human-in-the-loop policy. Finality (marking work done) can require explicit human acceptance, and a mediated permission model can lock capabilities down. → Finality and human sign-off
Read-only by default

ContextRelay is read-only by default. Read-only backup-agent autonomy is off until you run ctxrelay autonomy on. Autonomous edits (act:write) are off and fail closed behind multiple layered gates - a hard environment switch, a daily spend cap, allowlists, strict dual-idle conditions, and ephemeral git-worktree containment - and even then ContextRelay captures the diff and never commits, merges, or pushes. None of this is on out of the box. → Read-only by default

Local developer tooling - not a sandbox

ContextRelay is local developer tooling. It is not a hosted service, it is not endorsed by OpenAI or Anthropic, and it is not a security sandbox between tools you do not trust. It coordinates two agents you already run; it does not isolate them from each other or from your machine.

Next steps​