Content
# 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 **local-only** control plane that lets Claude Code and Codex work together on the same repo. It handles live messaging, a durable shared ledger, handoffs, headless reviewers, and a terminal + browser dashboard — all without sending your code anywhere.
One agent codes, another reviews, a headless worker gives a second opinion, and you keep full auditability. Everything stays on your machine.
**Local. Auditable. No cloud. No extra accounts.**
## Quick Start
```bash
# 1. Install the agents + ContextRelay
npm install -g @anthropic-ai/claude-code @openai/codex @proofofwork-agency/contextrelay
# 2. Set up the project
ctxrelay init --instructions project
ctxrelay codex-mcp install
# 3. Launch the pair
ctxrelay pair
```
Then inside Claude or Codex:
```text
/contextrelay:handoff review the auth changes
/contextrelay:deliberate is this design sound?
```
See the full [install guide](https://proofofwork-agency.github.io/contextrelay/docs/getting-started/install-and-first-run) or run `ctxrelay doctor`.
## What You Actually Get
| What | Why it matters |
|------|----------------|
| **One shared session for two native agents** | Claude Code and Codex keep their own UIs and models. ContextRelay just wires them together with one daemon, ledger, coordinator, and task board. |
| **Durable shared ledger** | Every message, handoff, note, artifact, test report, release gate, and headless result is append-only JSONL in `.contextrelay/`. Crash? Inspect and resume later. |
| **Structured handoffs & deliberation** | `/contextrelay:handoff` or `handoff_to_claude` passes a concrete ask + files + reason. `/contextrelay:deliberate` records a short debate before big decisions. |
| **Headless reviewers on demand** | `ctxrelay headless run --target codex` (or via the `contained_run` tool) spins up a fresh-context read-only worker. Supports `codex`, `claude`, and `opencode` (on macOS). |
| **Idle nudges** | With autonomy on, the daemon can politely ask the idle agent to pull the next task from the busy coordinator. |
| **Native TUI + viewer** | Full terminal dashboard for status, controls, and activity. Browser "Command Deck" for read-only inspection. |
| **Git writes stay with the coordinator** | Only the designated coordinator (Claude, Codex, or human) is allowed to commit, push, etc. Everyone else is read-only by default. |
| **Gated writes & release evidence** | `act:write` is off by default and runs in a contained worktree. `release-gate` records proof before you ship. |
| **Named sessions & worktrees** | Spin up side sessions bound to separate worktrees for parallel review or experiments. |
## Daily Workflow
```bash
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:
```text
/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`, `contained_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.
```bash
ctxrelay headless run \
--target codex \
--prompt "Review the current diff for release blockers. Findings first."
```
From MCP, call `contained_run`:
```json
{
"agent": "claude",
"prompt": "Review src/backup/runner.ts and tests for regressions.",
"context_refs": ["git diff", "src/backup/runner.ts"]
}
```
> **Renamed:** this tool was called `headless_run`. It collided with
> [Headless](https://github.com/proofofwork-agency/headless), a separate product that ships an MCP
> tool of the same name — an agent told to "use headless" would reach for the wrong one. The old
> name is still accepted for one version and still works in `CONTEXTRELAY_MCP_TOOLS` allowlists,
> but it is no longer advertised. ContextRelay's *feature* is still called headless workers; only
> the tool identifier changed.
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
```text
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:
```text
[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:
```bash
ctxrelay autonomy on
```
Disable just this nudge in `.contextrelay/config.json`:
```json
{
"autonomy": {
"idleScanner": {
"askForWork": {
"enabled": false
}
}
}
}
```
## Control Deck
The native TUI opens with `contextrelay` or `ctxrelay tui [--no-start] [--force]`.
<table>
<tr>
<td width="50%" valign="top">
<img src="docs/assets/contextrelay-tui-overview.png" alt="ContextRelay TUI overview"><br>
<b>Overview</b>: agents, daemon health, ports, ledger/queue counts, active sessions.
</td>
<td width="50%" valign="top">
<img src="docs/assets/contextrelay-tui-controls.png" alt="ContextRelay TUI controls"><br>
<b>Controls</b>: coordinator, autonomy, scanner, write mode, finality, read-only, usage preset.
</td>
</tr>
<tr>
<td width="50%" valign="top">
<img src="docs/assets/contextrelay-tui-activity.png" alt="ContextRelay TUI activity"><br>
<b>Activity</b>: handoffs, delivery state, idle-worker status, runtime events.
</td>
<td width="50%" valign="top">
<img src="docs/assets/contextrelay-tui-help.png" alt="ContextRelay TUI help"><br>
<b>Help</b>: press <code>h</code> for keys and policy notes.
</td>
</tr>
</table>
## 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.
- `contained_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/THREAT_MODEL.md](docs/THREAT_MODEL.md) before relying on any stronger boundary.
## Common Commands
```bash
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 <port>] [--session <id>]
ctxrelay status [--json]
ctxrelay viewer [--no-open]
ctxrelay release-gate [--json] [--smoke]
ctxrelay headless run --target <codex|claude|opencode> (--prompt <text>|--prompt-file <path>) [--timeout <ms>] [--label <name>] [--json]
ctxrelay kill [--all|--session <id>]
```
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](https://proofofwork-agency.github.io/contextrelay/)
- [Docs index](docs/README.md)
- [Operator runbook](docs/RUNBOOK.md)
- [Reference](docs/REFERENCE.md)
- [Changelog](CHANGELOG.md) — see v3.10.1 for hygiene and default fixes
- [CONTEXTRELAY_V1.md](docs/CONTEXTRELAY_V1.md)
- [ROADMAP.md](docs/ROADMAP.md)
- [RUNBOOK.md](docs/RUNBOOK.md)
- [SESSION-LIFECYCLE.md](docs/SESSION-LIFECYCLE.md)
- [THREAT_MODEL.md](docs/THREAT_MODEL.md)
The compact CLI reference is at the end of this file for sync purposes.
## Develop
```bash
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:
```bash
bun run check
```
Run package evidence before publishing:
```bash
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.
<details>
<summary>Compact release-sync reference</summary>
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`.
```text
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 <id>] [args...]
ctxrelay codex [--session <id>] [args...]
ctxrelay codex-mcp install|remove|status|server
ctxrelay pair [--dry-run] [--no-tui] [--port-base <port>] [--session <id>]
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 <capability>|deny <capability>|reset [--agent <agentId>]
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 <usd>]
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 <id>] [--recent <count>] [--preview-chars <count>]
ctxrelay usage ledger clear [--dry-run|--apply] [--session <id>]
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 <codex|claude|opencode> (--prompt <text>|--prompt-file <path>) [--timeout <ms>] [--label <name>] [--json]
ctxrelay kill [--all|--session <id>]
ctxrelay standalone on|off|status [--scope project|global|both] [--path <file>]
ctxrelay attach [session-name]
ctxrelay detach
ctxrelay gate-check [--status|--json|--why]
```
Claude MCP tools:
```text
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
contained_run
propose_final
```
Codex MCP tools:
```text
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
contained_run
propose_final
```
Claude slash commands:
```text
/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`.
</details>
