zarcherlot/code-relay

English · Chinese
Build. Prove. Relay.
> **Code Relay lets your coding agent develop on one machine and prove the result on another.**
Relay is an MCP-based coding-agent integration for cross-machine development and
verification. AI on the Dev Host implements the request; the Target Host runs
the real validation; a structured receipt comes back to guide the next repair
iteration. It works with Codex, Claude Code, Cursor, VS Code, and other
MCP-capable coding agents.
When Relay is useful
- **Different environments** — develop on Windows or macOS, verify on Linux, a private network, or a production-like host.
- **Special hardware** — send model code to a CUDA/GPU machine, or verify a camera, serial device, or sensor where it is connected.
- **Real integrations** — exercise payment callbacks, queues, databases, browsers, or internal services that cannot be reproduced locally.
- **AI-driven iteration** — return concrete expected/actual results so the coding agent can repair, republish, and retry.
What Relay provides
- Branch-scoped project binding and short-lived join links.
- Exact source-commit verification in an isolated worktree.
- Checkpoint execution through a code-relay-checkpoint GitHub Actions self-hosted runner.
- Safe, allowlisted validation commands with bounded output and timeouts.
- Structured receipt.json and human-readable receipts for passed, failed, and blocked runs.
Quick start
AI client installation
Let your coding agent read and follow the instructions:
npm fallback
Replace codex with claude-code, cursor, vscode, or generic as needed.
MCP server details
Code Relay is a local MCP server that communicates over **stdio**. The npm
package starts the server with:
The server implements the MCP JSON-RPC surface directly in Go (without a
third-party MCP SDK). It supports initialize, ping, tools/list, and
tools/call, and exposes these tools:
| Tool | Purpose |
| --- | --- |
| bind_project | Bind a repository and branch to a relay role. |
| create_checkpoint_invite | Create a short-lived checkpoint join link. |
| join_checkpoint | Join a branch-scoped checkpoint subscription. |
| watcher_status | Read local watcher state. |
| stop_watcher | Stop the local watcher. |
| doctor | Run non-mutating local health checks. |
| publish_runbook | Validate and publish a runbook. |
| status | Read runbook and receipt status. |
| fetch_receipt | Load and validate a runbook receipt. |
| analyze | Analyze a receipt and determine the next state. |