{"id":49955294,"url":"https://github.com/proofofwork-agency/contextrelay","last_synced_at":"2026-07-10T01:00:25.455Z","repository":{"id":357472807,"uuid":"1236871389","full_name":"proofofwork-agency/contextrelay","owner":"proofofwork-agency","description":"Run Claude Code and Codex as one auditable local coding team — live handoffs, a shared ledger, and human-gated autonomy. Claude Code plugin + MCP server.","archived":false,"fork":false,"pushed_at":"2026-06-24T22:44:36.000Z","size":3838,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T23:07:07.188Z","etag":null,"topics":["agent-orchestration","ai-agents","audit-log","claude-code","codex","developer-tools","local-first","mcp","model-context-protocol","multi-agent","openai-codex"],"latest_commit_sha":null,"homepage":"https://proofofwork-agency.github.io/contextrelay/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/proofofwork-agency.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-12T16:47:45.000Z","updated_at":"2026-06-24T22:44:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/proofofwork-agency/contextrelay","commit_stats":null,"previous_names":["proofofwork-agency/contextrelay"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/proofofwork-agency/contextrelay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proofofwork-agency%2Fcontextrelay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proofofwork-agency%2Fcontextrelay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proofofwork-agency%2Fcontextrelay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proofofwork-agency%2Fcontextrelay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/proofofwork-agency","download_url":"https://codeload.github.com/proofofwork-agency/contextrelay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proofofwork-agency%2Fcontextrelay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35316840,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","ai-agents","audit-log","claude-code","codex","developer-tools","local-first","mcp","model-context-protocol","multi-agent","openai-codex"],"created_at":"2026-05-17T23:01:52.840Z","updated_at":"2026-07-10T01:00:25.373Z","avatar_url":"https://github.com/proofofwork-agency.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ContextRelay\n\n[![npm version](https://img.shields.io/npm/v/@proofofwork-agency/contextrelay.svg)](https://www.npmjs.com/package/@proofofwork-agency/contextrelay)\n[![npm downloads](https://img.shields.io/npm/dm/@proofofwork-agency/contextrelay.svg)](https://www.npmjs.com/package/@proofofwork-agency/contextrelay)\n[![CI](https://github.com/proofofwork-agency/contextrelay/actions/workflows/ci.yml/badge.svg)](https://github.com/proofofwork-agency/contextrelay/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-online-4f46e5.svg)](https://proofofwork-agency.github.io/contextrelay/)\n\n\u003e **Run Claude Code and Codex as one local coding team.**\n\nContextRelay 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.\n\nOne agent codes, another reviews, a headless worker gives a second opinion, and you keep full auditability. Everything stays on your machine.\n\n![ContextRelay running Claude Code and Codex as one pair, with a live shared ledger](docs/assets/contextrelay-pair.gif)\n\n**Local. Auditable. No cloud. No extra accounts.**\n\n## Quick Start\n\n```bash\n# 1. Install the agents + ContextRelay\nnpm install -g @anthropic-ai/claude-code @openai/codex @proofofwork-agency/contextrelay\n\n# 2. Set up the project\nctxrelay init --instructions project\nctxrelay codex-mcp install\n\n# 3. Launch the pair\nctxrelay pair\n```\n\nThen inside Claude or Codex:\n\n```text\n/contextrelay:handoff review the auth changes\n/contextrelay:deliberate is this design sound?\n```\n\nSee the full [install guide](https://proofofwork-agency.github.io/contextrelay/docs/getting-started/install-and-first-run) or run `ctxrelay doctor`.\n\n## What You Actually Get\n\n| What | Why it matters |\n|------|----------------|\n| **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. |\n| **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. |\n| **Structured handoffs \u0026 deliberation** | `/contextrelay:handoff` or `handoff_to_claude` passes a concrete ask + files + reason. `/contextrelay:deliberate` records a short debate before big decisions. |\n| **Headless reviewers on demand** | `ctxrelay headless run --target codex` (or via `headless_run` tool) spins up a fresh-context read-only worker. Supports `codex`, `claude`, and `opencode` (on macOS). |\n| **Idle nudges** | With autonomy on, the daemon can politely ask the idle agent to pull the next task from the busy coordinator. |\n| **Native TUI + viewer** | Full terminal dashboard for status, controls, and activity. Browser \"Command Deck\" for read-only inspection. |\n| **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. |\n| **Gated writes \u0026 release evidence** | `act:write` is off by default and runs in a contained worktree. `release-gate` records proof before you ship. |\n| **Named sessions \u0026 worktrees** | Spin up side sessions bound to separate worktrees for parallel review or experiments. |\n\n## Daily Workflow\n\n```bash\nctxrelay pair              # launch Claude + Codex around this project\nctxrelay viewer            # open the read-only browser command deck\nctxrelay ledger list       # inspect the shared ledger\nctxrelay headless run --target codex --prompt \"Review this diff for release blockers\"\nctxrelay release-gate      # record release evidence\nctxrelay kill              # stop this project daemon\n```\n\nInside Claude Code:\n\n```text\n/contextrelay:handoff review the risky part of this change\n/contextrelay:deliberate should this be a protocol change or display-only?\n/contextrelay:finalize\n```\n\nFrom 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.\n\nThe everyday loop is simple: one agent does the work, the other reviews or challenges it, and ContextRelay keeps the useful context written down.\n\n## Headless Reviews\n\nHeadless jobs are one-shot reviewers. They do not join the live pair; they inspect context and return one result.\n\n```bash\nctxrelay headless run \\\n  --target codex \\\n  --prompt \"Review the current diff for release blockers. Findings first.\"\n```\n\nFrom MCP, call `headless_run`:\n\n```json\n{\n  \"agent\": \"claude\",\n  \"prompt\": \"Review src/backup/runner.ts and tests for regressions.\",\n  \"context_refs\": [\"git diff\", \"src/backup/runner.ts\"]\n}\n```\n\nRegistered contained adapters are exposed automatically. Built-ins today:\n\n- `codex`: `codex exec --sandbox read-only`\n- `claude`: `claude -p` with read-only tools\n- `opencode`: `opencode run --pure` inside the Darwin read-only sandbox when the binary and sandbox probe are available\n\nThe `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`.\n\n`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.\n\nAdapters 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.\n\n## Pair Work\n\n![A Claude-to-Codex review handoff recorded in the ContextRelay ledger](docs/assets/contextrelay-handoff.gif)\n\n```text\nClaude -\u003e /contextrelay:handoff\n  reason: finished the token refresh change; want a second opinion before merge\n  ask:    review src/auth/refresh.ts for races and token leak paths\n  files:  src/auth/refresh.ts, src/auth/refresh.test.ts\n\nCodex -\u003e reply\n  Two issues: refresh is not single-flight, and the old token remains in memory\n  after rotation. Tests pass, but neither path is covered.\n\nClaude -\u003e append_note\n  decision: add the single-flight lock, zero the old token, add both tests.\n```\n\n## Idle Ask-For-Work\n\nWhen global autonomy is on, ContextRelay can keep the non-coordinator from silently sitting idle.\n\nIf Codex is coordinator and currently busy while Claude is idle, the daemon nudges Claude:\n\n```text\n[IMPORTANT] ASK_FOR_WORK: You appear idle while the coordinator is actively working.\nAsk Codex for the next concrete task now, and include either what you just finished or that you are ready for work.\n```\n\nIf 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.\n\nEnable the autonomy master switch:\n\n```bash\nctxrelay autonomy on\n```\n\nDisable just this nudge in `.contextrelay/config.json`:\n\n```json\n{\n  \"autonomy\": {\n    \"idleScanner\": {\n      \"askForWork\": {\n        \"enabled\": false\n      }\n    }\n  }\n}\n```\n\n## Control Deck\n\nThe native TUI opens with `contextrelay` or `ctxrelay tui [--no-start] [--force]`.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\" valign=\"top\"\u003e\n      \u003cimg src=\"docs/assets/contextrelay-tui-overview.png\" alt=\"ContextRelay TUI overview\"\u003e\u003cbr\u003e\n      \u003cb\u003eOverview\u003c/b\u003e: agents, daemon health, ports, ledger/queue counts, active sessions.\n    \u003c/td\u003e\n    \u003ctd width=\"50%\" valign=\"top\"\u003e\n      \u003cimg src=\"docs/assets/contextrelay-tui-controls.png\" alt=\"ContextRelay TUI controls\"\u003e\u003cbr\u003e\n      \u003cb\u003eControls\u003c/b\u003e: coordinator, autonomy, scanner, write mode, finality, read-only, usage preset.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\" valign=\"top\"\u003e\n      \u003cimg src=\"docs/assets/contextrelay-tui-activity.png\" alt=\"ContextRelay TUI activity\"\u003e\u003cbr\u003e\n      \u003cb\u003eActivity\u003c/b\u003e: handoffs, delivery state, idle-worker status, runtime events.\n    \u003c/td\u003e\n    \u003ctd width=\"50%\" valign=\"top\"\u003e\n      \u003cimg src=\"docs/assets/contextrelay-tui-help.png\" alt=\"ContextRelay TUI help\"\u003e\u003cbr\u003e\n      \u003cb\u003eHelp\u003c/b\u003e: press \u003ccode\u003eh\u003c/code\u003e for keys and policy notes.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Safety Model\n\nContextRelay assumes one trusted operator on one workstation.\n\n- The daemon binds to `127.0.0.1`.\n- The viewer cannot dispatch agent work; it can clear current-session history\n  through its authenticated local maintenance endpoint.\n- Git writes are policy-routed through one coordinator or the human.\n- Autonomy is off by default.\n- `headless_run` is read-only and only accepts registered contained adapters.\n- `act:write` is default-off and only runs in an ephemeral git worktree behind dual-idle, budget, single-flight, and containment gates.\n- Provider CLIs still use their own auth and approval systems.\n\nRead [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) before relying on any stronger boundary.\n\n## Common Commands\n\n```bash\ncontextrelay                  # open the native ContextRelay TUI\nctxrelay init --instructions project\nctxrelay codex-mcp install|remove|status|server\nctxrelay pair [--dry-run] [--no-tui] [--port-base \u003cport\u003e] [--session \u003cid\u003e]\nctxrelay status [--json]\nctxrelay viewer [--no-open]\nctxrelay release-gate [--json] [--smoke]\nctxrelay headless run --target \u003ccodex|claude|opencode\u003e (--prompt \u003ctext\u003e|--prompt-file \u003cpath\u003e) [--timeout \u003cms\u003e] [--label \u003cname\u003e] [--json]\nctxrelay kill [--all|--session \u003cid\u003e]\n```\n\nThe 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).\n\n## Documentation\n\n- [Docs site](https://proofofwork-agency.github.io/contextrelay/)\n- [Docs index](docs/README.md)\n- [Operator runbook](docs/RUNBOOK.md)\n- [Reference](docs/REFERENCE.md)\n- [Changelog](CHANGELOG.md) — see v3.10.1 for hygiene and default fixes\n- [CONTEXTRELAY_V1.md](docs/CONTEXTRELAY_V1.md)\n- [ROADMAP.md](docs/ROADMAP.md)\n- [RUNBOOK.md](docs/RUNBOOK.md)\n- [SESSION-LIFECYCLE.md](docs/SESSION-LIFECYCLE.md)\n- [THREAT_MODEL.md](docs/THREAT_MODEL.md)\n\nThe compact CLI reference is at the end of this file for sync purposes.\n\n## Develop\n\n```bash\ngit clone https://github.com/proofofwork-agency/contextrelay.git\ncd contextrelay\nbun install\nbun run build:cli\nbun run build:plugin\nbun link\nbun link @proofofwork-agency/contextrelay\nctxrelay init --instructions project\nctxrelay codex-mcp install\nctxrelay pair\n```\n\nRun the local gate:\n\n```bash\nbun run check\n```\n\nRun package evidence before publishing:\n\n```bash\nctxrelay release-gate --json\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE). ContextRelay preserves the original AgentBridge MIT copyright notice and adds the ProofOfWork / Danillo Felixdaal copyright notice for this fork's changes.\n\n\u003cdetails\u003e\n\u003csummary\u003eCompact release-sync reference\u003c/summary\u003e\n\nThis section keeps the README synchronized with the public CLI and tool surface. Most readers should use [docs/REFERENCE.md](docs/REFERENCE.md) instead.\n\nCLI aliases: `contextrelay`, `context-relay`, `ctxrelay`.\n\n```text\ncontextrelay\nctxrelay tui [--no-start] [--force]\nctxrelay init [--instructions project|global|both|skip]\nctxrelay upgrade [--dry-run] [--no-plugin] [--instructions refresh|project|global|both|skip]\nctxrelay dev\nctxrelay claude [--session \u003cid\u003e] [args...]\nctxrelay codex [--session \u003cid\u003e] [args...]\nctxrelay codex-mcp install|remove|status|server\nctxrelay pair [--dry-run] [--no-tui] [--port-base \u003cport\u003e] [--session \u003cid\u003e]\nctxrelay doctor [--no-auth]\nctxrelay instructions status|install|remove [--scope project|global|both]\nctxrelay coordinator [status|claude|codex|human] [--scope project|global|both]\nctxrelay permissions status|readonly on|off|allow \u003ccapability\u003e|deny \u003ccapability\u003e|reset [--agent \u003cagentId\u003e]\nctxrelay detach-claude\nctxrelay status [--json]\nctxrelay session list|create|select|archive|rebind [...]\nctxrelay recover [--json]\nctxrelay instances\nctxrelay viewer [--no-open]\nctxrelay autonomy on|off|status\nctxrelay idle-scanner off|suggest|ask|act|status [--why]|check\nctxrelay idle-budget status|reset\nctxrelay idle-eval status|compare\nctxrelay act on|off|status [--budget \u003cusd\u003e]\nctxrelay finalize auto|manual|status\nctxrelay usage status|off|lean|strict\nctxrelay usage hook status|verbose|compact|count|set\nctxrelay usage context off|lean|strict|status\nctxrelay usage ledger compact [--dry-run|--apply] [--session \u003cid\u003e] [--recent \u003ccount\u003e] [--preview-chars \u003ccount\u003e]\nctxrelay usage ledger clear [--dry-run|--apply] [--session \u003cid\u003e]\nctxrelay hook-compaction status|verbose|compact|count|set\nctxrelay usage-control off|lean|strict|status\nctxrelay ledger list|show|compact|clear [...]\nctxrelay queue list|show|remove|drain [...]\nctxrelay messages status|drain [...]\nctxrelay release-gate [--json] [--smoke]\nctxrelay headless run --target \u003ccodex|claude|opencode\u003e (--prompt \u003ctext\u003e|--prompt-file \u003cpath\u003e) [--timeout \u003cms\u003e] [--label \u003cname\u003e] [--json]\nctxrelay kill [--all|--session \u003cid\u003e]\nctxrelay standalone on|off|status [--scope project|global|both] [--path \u003cfile\u003e]\nctxrelay attach [session-name]\nctxrelay detach\nctxrelay gate-check [--status|--json|--why]\n```\n\nClaude MCP tools:\n\n```text\nreply\nget_messages\nwait_for_messages\nhandoff\ndeliberate_with_codex\nappend_note\nread_context\nsession_info\ncreate_session\nselect_session\narchive_session\nrebind_session\ntask_state\nrecord_artifact\nask_codex_backup\nbackup_status\nheadless_run\npropose_final\n```\n\nCodex MCP tools:\n\n```text\nsend_to_claude\nhandoff_to_claude\ndeliberate_with_claude\nread_context\nwait_for_claude\nappend_note\nsession_info\ncreate_session\nselect_session\narchive_session\nrebind_session\ntask_state\nrecord_artifact\nask_claude_backup\nbackup_status\nheadless_run\npropose_final\n```\n\nClaude slash commands:\n\n```text\n/contextrelay:init\n/contextrelay:status\n/contextrelay:handoff\n/contextrelay:review\n/contextrelay:deliberate\n/contextrelay:finalize\n/contextrelay:on\n/contextrelay:off\n```\n\nArtifact 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`.\n\nArtifact statuses: `passed`, `failed`, `blocked`, `unknown`, `skipped`, `timed_out`.\n\nCore 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`.\n\nClaude Code host env vars read by bundled hooks: `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PROJECT_DIR`.\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproofofwork-agency%2Fcontextrelay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproofofwork-agency%2Fcontextrelay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproofofwork-agency%2Fcontextrelay/lists"}