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, one-shot headless reviewers for fresh-context second opinions, idle ask-for-work nudges when one side is waiting for direction, 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.

Scripted demo using real ctxrelay output format — paths, IDs, and timestamps are sanitized.

Current docs

These docs track the current repository docs for @proofofwork-agency/contextrelay. 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

Once they're paired, a handoff looks like this — Claude asks Codex for an independent review, and every message lands in the shared ledger:

Scripted from the real ctxrelay ledger format; the scenario is representative.

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:

Command	When to use it
ctxrelay upgrade	Run 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 on	Make 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
• Spin up fresh-context reviewers. contained_run and ctxrelay headless run dispatch one read-only worker through the registered adapter system (codex, claude, and supported opencode setups). → Headless workers and adapters
• Keep the idle side engaged. With autonomy enabled, the daemon can nudge an idle non-coordinator to ask the active coordinator for the next concrete task, and records the event as an idle_ask_for_work artifact. → Autonomy, idle scanner, and safe automation
• 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 adapter surface for throwaway reviewers. contained_run is the single MCP tool for registered terminal-coder adapters. Adapters are reviewed source-level additions, not external drop-in plugins; adding one extends the enum instead of adding a new public tool. → Headless workers and adapters
• 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 - the global autonomy switch, explicit act config, a positive daily spend cap, 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

• What is ContextRelay - the full picture: daemon, ledger, TUI, and viewer.
• Why two agents in one session - the principle behind the design.
• Install and first run - the detailed setup walkthrough.
• CLI command reference - every command and flag.