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-checkpointGitHub Actions self-hosted runner. - Safe, allowlisted validation commands with bounded output and timeouts.
- Structured
receipt.jsonand human-readable receipts for passed, failed, and blocked runs.
Quick start
AI client installation
Let your coding agent read and follow the instructions:```text
https://raw.githubusercontent.com/zarcherlot/code-relay/main/install.md
### npm fallback```sh
npx -y code-relay-mcp@latest install --client codex
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:sh
npx -y code-relay-mcp@3.1.0
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. |
The implementation and transport loop are in internal/relay/mcp.go.
How it works
the Dev Host sends a repository- and branch-bound runbook
through Relay; the Target Host checks the exact source commit in its real
environment and returns a Receipt recording the Checkpoint result.
Every runbook is bound to a repository, branch, and source commit. The Target
Host acts as the Checkpoint, and the resulting receipt records passed, failed,
or blocked verification for the next iteration.
Documentation
- Chinese README
- User guide
- AI-client installation guide
- Local desktop install runbook
- Deployment and runbook
- Security
- Contributing
License
Code Relay is released under the MIT License.
