Contextrelay

ContextRelay

[](https://www.npmjs.com/package/@proofofwork-agency/contextrelay) [](https://www.npmjs.com/package/@proofofwork-agency/contextrelay) [](https://github.com/proofofwork-agency/contextrelay/actions/workflows/ci.yml) [](LICENSE) [](https://proofofwork-agency.github.io/contextrelay/)

Run Claude Code and Codex as one local coding team.

ContextRelay is a provider-neutral control plane for agentic coding work. It connects Claude Code and Codex to the same repository, routes live messages between them, records every handoff and artifact in a shared ledger, and gives you a terminal dashboard plus a read-only browser command deck for the session.

It is built for the workflow where one agent implements, the other reviews, a third headless worker gives a fresh-context opinion, and the human can still audit exactly what happened before anything ships.

No hosted service. No account proxy. No fake "AI swarm" abstraction. It is local developer tooling around the CLIs you already run.

The Sharp Edges It Adds

| Feature | What you actually get | | --- | --- | | Two native agents, one session | Claude Code and Codex stay their own products, but ContextRelay gives them one daemon, one shared state, one coordinator, and one task board. | | A durable shared ledger | Messages, handoffs, notes, artifacts, test reports, release gates, finality proposals, and headless results are written as JSONL under .contextrelay/. If a session crashes, you can inspect and recover it. | | Structured handoffs and deliberation | Agents can transfer a bounded task with a reason, files, and a concrete ask, or run a short recorded debate on an architecture/release decision. | | Fresh-context headless workers | headless_run and ctxrelay headless run start one read-only worker through the registered adapter system: codex, claude, and, on supported hosts, opencode. Fan out multiple reviewers from workflows; the daemon pools and budgets them. | | Adapter-based headless architecture | Built-in terminal-coder adapters implement one HeadlessAdapter interface: command, env, prompt delivery, output parser, containment proof, and optional grounding prompt. Adapters are not external drop-in plugins yet; new adapters land through reviewed PRs and then appear in headless_run. | | Idle ask-for-work nudges | When autonomy is enabled and the coordinator is working while the other agent is idle, the daemon can nudge the idle agent to ask for the next concrete task. It works both directions: Claude can ask Codex, or Codex can ask Claude. | | Native control surfaces | The terminal TUI shows daemon health, ports, sessions, queue depth, agent state, coordinator, autonomy, finality, idle workers, and activity. The browser viewer is inspection-only for agent work, with authenticated local history cleanup. | | Named runtime sessions | Optional named sessions can bind to separate worktrees for review/debug lanes while keeping runtime metadata explicit. | | Coordinator-owned git policy | Claude, Codex, or the human can be the coordinator. Git-sensitive work routes through that owner so two agents do not race branch, commit, merge, push, or PR operations. | | Read-only by default, gated writes | Backup agents and headless workers are read-only. Autonomous edits (act:write) are off by default and, when armed, run in an ephemeral git worktree behind strict gates; ContextRelay captures the diff and never commits, merges, or pushes for you. | | Release evidence and finality | ctxrelay release-gate records package/check evidence. propose_final and finality settings make "done" an auditable event instead of a chat vibe. |

Install

You need Bun, Claude Code, and Codex on PATH.

npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
npm install -g @proofofwork-agency/contextrelay

ctxrelay init --instructions project
ctxrelay codex-mcp install
contextrelay

contextrelay, ctxrelay, and context-relay are the same CLI. ctxrelay init creates .contextrelay/config.json, installs the Claude Code plugin, writes managed ContextRelay blocks into AGENTS.md and CLAUDE.md, and prepares the project daemon. ctxrelay codex-mcp install registers the Codex MCP tools globally for your Codex user.

Check the install:

ctxrelay doctor
ctxrelay status
ctxrelay instances

Already installed? Run this after upgrading the npm package:

ctxrelay upgrade

Daily Workflow

ctxrelay pair              # launch Claude + Codex around this project
ctxrelay viewer            # open the read-only browser command deck
ctxrelay ledger list       # inspect the shared ledger
ctxrelay headless run --target codex --prompt "Review this diff for release blockers"
ctxrelay release-gate      # record release evidence
ctxrelay kill              # stop this project daemon

Inside Claude Code:

/contextrelay:handoff review the risky part of this change
/contextrelay:deliberate should this be a protocol change or display-only?
/contextrelay:finalize

From Codex, use the MCP tools after ctxrelay codex-mcp install: handoff_to_claude, deliberate_with_claude, headless_run, read_context, record_artifact, propose_final, and the rest of the ContextRelay tool surface.

The everyday loop is simple: one agent does the work, the other reviews or challenges it, and ContextRelay keeps the useful context written down.

Headless Reviews

Headless jobs are one-shot reviewers. They do not join the live pair; they inspect context and return one result.

ctxrelay headless run \
  --target codex \
  --prompt "Review the current diff for release blockers. Findings first."

From MCP, call headless_run:

{
  "agent": "claude",
  "prompt": "Review src/backup/runner.ts and tests for regressions.",
  "context_refs": ["git diff", "src/backup/runner.ts"]
}

Registered contained adapters are exposed automatically. Built-ins today:

• codex: codex exec --sandbox read-only
• claude: claude -p with read-only tools
• opencode: opencode run --pure inside the Darwin read-only sandbox when the binary and sandbox probe are available

The opencode adapter is optional. If you want to use --target opencode, install and authenticate the opencode CLI first and make sure opencode is on PATH for the daemon or CLI process. ContextRelay registers the adapter automatically only on macOS/Darwin when opencode is present and the sandbox-exec write-denial probe passes. To hide just this adapter, start ContextRelay with CONTEXTRELAY_OPENCODE_ENABLED=0; to disable every headless worker, use CONTEXTRELAY_HEADLESS_ENABLED=0.

opencode gets an extra grounding preamble because it runs in minimal --pure mode. It is told exactly which read-only tools exist and not to claim edits, tests, or shell commands it cannot perform. Codex and Claude are left to their native headless runtimes.

Adapters are source-level extension points, not external runtime plugins. To add another terminal-coder target, open a PR that implements HeadlessAdapter in src/backup, registers it in the in-process adapter registry, and includes containment proof, env allowlist, output parsing, tests, and docs. After review and release, users get the adapter through the normal npm package update.

Pair Work

Claude -> /contextrelay:handoff
  reason: finished the token refresh change; want a second opinion before merge
  ask:    review src/auth/refresh.ts for races and token leak paths
  files:  src/auth/refresh.ts, src/auth/refresh.test.ts

Codex -> reply
  Two issues: refresh is not single-flight, and the old token remains in memory
  after rotation. Tests pass, but neither path is covered.

Claude -> append_note
  decision: add the single-flight lock, zero the old token, add both tests.

Idle Ask-For-Work

When global autonomy is on, ContextRelay can keep the non-coordinator from silently sitting idle.

If Codex is coordinator and currently busy while Claude is idle, the daemon nudges Claude:

[IMPORTANT] ASK_FOR_WORK: You appear idle while the coordinator is actively working.
Ask Codex for the next concrete task now, and include either what you just finished or that you are ready for work.

If Claude is coordinator and Codex is idle, the same mechanism injects the nudge into Codex. The feature is automatic, cooldown-limited, and records an idle_ask_for_work artifact in the ledger. It is not a public MCP tool; it is daemon behavior controlled by config.

Enable the autonomy master switch:

ctxrelay autonomy on

Disable just this nudge in .contextrelay/config.json:

{
  "autonomy": {
    "idleScanner": {
      "askForWork": {
        "enabled": false
      }
    }
  }
}

Control Deck

The native TUI opens with contextrelay or ctxrelay tui [--no-start] [--force].

Overview: agents, daemon health, ports, ledger/queue counts, active sessions.

Controls: coordinator, autonomy, scanner, write mode, finality, read-only, usage preset.

Activity: handoffs, delivery state, idle-worker status, runtime events.

Help: press h for keys and policy notes.

Safety Model

ContextRelay assumes one trusted operator on one workstation.

• The daemon binds to 127.0.0.1.
• The viewer cannot dispatch agent work; it can clear current-session history

through its authenticated local maintenance endpoint.

• Git writes are policy-routed through one coordinator or the human.
• Autonomy is off by default.
• headless_run is read-only and only accepts registered contained adapters.
• act:write is default-off and only runs in an ephemeral git worktree behind dual-idle, budget, single-flight, and containment gates.
• Provider CLIs still use their own auth and approval systems.

Read [docs/THREATMODEL.md](docs/THREATMODEL.md) before relying on any stronger boundary.

Common Commands

contextrelay                  # open the native ContextRelay TUI
ctxrelay init --instructions project
ctxrelay codex-mcp install|remove|status|server
ctxrelay pair [--dry-run] [--no-tui] [--port-base ] [--session ]
ctxrelay status [--json]
ctxrelay viewer [--no-open]
ctxrelay release-gate [--json] [--smoke]
ctxrelay headless run --target  (--prompt |--prompt-file ) [--timeout ] [--label ] [--json]
ctxrelay kill [--all|--session ]

The full command, MCP, environment, metrics, and artifact reference lives in [docs/REFERENCE.md](docs/REFERENCE.md). Day-to-day recovery lives in [docs/RUNBOOK.md](docs/RUNBOOK.md).

Documentation

• Docs site
• [Docs index](docs/README.md)
• [Operator runbook](docs/RUNBOOK.md)
• [Reference](docs/REFERENCE.md)
• [Runtime architecture](docs/CONTEXTRELAY_V1.md)
• [Session lifecycle](docs/SESSION-LIFECYCLE.md)
• [Threat model](docs/THREAT_MODEL.md)
• [Roadmap](docs/ROADMAP.md)
• [Changelog](CHANGELOG.md)

Develop

git clone https://github.com/proofofwork-agency/contextrelay.git
cd contextrelay
bun install
bun run build:cli
bun run build:plugin
bun link
bun link @proofofwork-agency/contextrelay
ctxrelay init --instructions project
ctxrelay codex-mcp install
ctxrelay pair

Run the local gate:

bun run check

Run package evidence before publishing:

ctxrelay release-gate --json

License

MIT. See [LICENSE](LICENSE). ContextRelay preserves the original AgentBridge MIT copyright notice and adds the ProofOfWork / Danillo Felixdaal copyright notice for this fork's changes.

Compact release-sync reference

This section keeps the README synchronized with the public CLI and tool surface. Most readers should use [docs/REFERENCE.md](docs/REFERENCE.md) instead.

CLI aliases: contextrelay, context-relay, ctxrelay.

contextrelay
ctxrelay tui [--no-start] [--force]
ctxrelay init [--instructions project|global|both|skip]
ctxrelay upgrade [--dry-run] [--no-plugin] [--instructions refresh|project|global|both|skip]
ctxrelay dev
ctxrelay claude [--session ] [args...]
ctxrelay codex [--session ] [args...]
ctxrelay codex-mcp install|remove|status|server
ctxrelay pair [--dry-run] [--no-tui] [--port-base ] [--session ]
ctxrelay doctor [--no-auth]
ctxrelay instructions status|install|remove [--scope project|global|both]
ctxrelay coordinator [status|claude|codex|human] [--scope project|global|both]
ctxrelay permissions status|readonly on|off|allow |deny |reset [--agent ]
ctxrelay detach-claude
ctxrelay status [--json]
ctxrelay session list|create|select|archive|rebind [...]
ctxrelay recover [--json]
ctxrelay instances
ctxrelay viewer [--no-open]
ctxrelay autonomy on|off|status
ctxrelay idle-scanner off|suggest|ask|act|status [--why]|check
ctxrelay idle-budget status|reset
ctxrelay idle-eval status|compare
ctxrelay act on|off|status [--budget ]
ctxrelay finalize auto|manual|status
ctxrelay usage status|off|lean|strict
ctxrelay usage hook status|verbose|compact|count|set
ctxrelay usage context off|lean|strict|status
ctxrelay usage ledger compact [--dry-run|--apply] [--session ] [--recent ] [--preview-chars ]
ctxrelay usage ledger clear [--dry-run|--apply] [--session ]
ctxrelay hook-compaction status|verbose|compact|count|set
ctxrelay usage-control off|lean|strict|status
ctxrelay ledger list|show|compact|clear [...]
ctxrelay queue list|show|remove|drain [...]
ctxrelay messages status|drain [...]
ctxrelay release-gate [--json] [--smoke]
ctxrelay headless run --target  (--prompt |--prompt-file ) [--timeout ] [--label ] [--json]
ctxrelay kill [--all|--session ]
ctxrelay standalone on|off|status [--scope project|global|both] [--path ]
ctxrelay attach [session-name]
ctxrelay detach
ctxrelay gate-check [--status|--json|--why]

Claude MCP tools:

reply
get_messages
wait_for_messages
handoff
deliberate_with_codex
append_note
read_context
session_info
create_session
select_session
archive_session
rebind_session
task_state
record_artifact
ask_codex_backup
backup_status
headless_run
propose_final

Codex MCP tools:

send_to_claude
handoff_to_claude
deliberate_with_claude
read_context
wait_for_claude
append_note
session_info
create_session
select_session
archive_session
rebind_session
task_state
record_artifact
ask_claude_backup
backup_status
headless_run
propose_final

Claude slash commands:

/contextrelay:init
/contextrelay:status
/contextrelay:handoff
/contextrelay:review
/contextrelay:deliberate
/contextrelay:finalize
/contextrelay:on
/contextrelay:off

Artifact kinds: patch_summary, release_gate, test_report, command_log, escalation_suggestion, idle_opportunity, idle_ask_for_work, idle_action_result, idle_fleet_result, idle_evaluation_result, idle_write_result, headless_result.

Artifact statuses: passed, failed, blocked, unknown, skipped, timed_out.

Core env vars: CONTEXTRELAY_STATE_DIR, CONTEXTRELAY_CONTROL_PORT, CODEX_WS_PORT, CODEX_PROXY_PORT, CONTEXTRELAY_PORT_BASE, CONTEXTRELAY_PROJECT_ROOT, CONTEXTRELAY_INSTANCE_ID, CONTEXTRELAY_AUTO_CONNECT, CONTEXTRELAY_MODE, CONTEXTRELAY_MCP_TOOLS, CONTEXTRELAY_ALLOW_NAMED_SESSIONS, CONTEXTRELAY_MAX_BUFFERED_MESSAGES, CONTEXTRELAY_IDLE_SCANNER, CONTEXTRELAY_HEADLESS_ENABLED, CONTEXTRELAY_OPENCODE_ENABLED.

Claude Code host env vars read by bundled hooks: CLAUDE_PLUGIN_ROOT, CLAUDE_PROJECT_DIR.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: proofofwork-agency
• Source: proofofwork-agency/contextrelay
• License: MIT
• Homepage: https://proofofwork-agency.github.io/contextrelay/

Install and usage instructions live in the source repository linked above.