What can you do with Code 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. It is optimized for the ChatGPT/Codex plugin surface, while the same MCP server also works with Claude Code, Cursor, VS Code, and other MCP-capable coding agents. AI on the Dev Host implements the request; the Target Host runs the real validation; a structured receipt comes back and can trigger the next repair iteration.

How it works

Describe the change in your coding agent
        ↓
Dev Host → Relay runbook → Target Host
        ↓                 ↓
     develop          checkpoint in the real environment
        ←────── Receipt / evidence ──────

Relay binds every runbook to a repository, branch, and source commit. The Target Host acts as the checkpoint, verifies the exact code you intended to ship, and returns an auditable receipt for passed, failed, or blocked results.

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.

Quick start

Install Code Relay from the ChatGPT/Codex plugin UI, or configure the MCP server in another coding agent.
On the Dev Host, open a project and say:

Enable Code Relay for the current project and branch, then generate a Target Host join link.
On the Target Host, install the same plugin or MCP server and paste the link into the coding agent.
The Target Host joins the approved repository and branch as its checkpoint, executes runbooks on the code-relay-checkpoint GitHub Actions runner, and publishes a receipt.

Users do not need to install Python, Go, or a separate Relay runtime for the packaged plugin. See USER_GUIDE.md for the complete journey and recovery steps.

Install through npm (any MCP client)

Code Relay is also distributed as code-relay-mcp. Any MCP-capable coding agent can follow install.md, or you can preview and apply the client-specific installer directly:

npx -y code-relay-mcp@latest install --client codex
npx -y code-relay-mcp@latest install --client codex --yes

For a persistent command, install it globally first:

npm install --global code-relay-mcp
code-relay-mcp install --client codex --yes

Replace codex with claude-code, cursor, vscode, or generic as needed. Node.js 18+ is required. The npm launcher downloads the matching native release binary on first use, verifies it against SHA256SUMS, and caches it locally; Go is not required. The npm distribution exposes the MCP tools. The ChatGPT/Codex plugin package additionally supplies the $code-relay:relay and $code-relay:checkpoint Skills; other clients can use the same MCP tools directly.

Install from this repository (local desktop)

The repository includes a repo-scoped marketplace at .agents/plugins/marketplace.json. To install from a source checkout, build the platform package once from the repository root:

pwsh -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\package-plugin.ps1 `
  -Output .\dist\plugin

This creates the native agent and packaged .mcp.json under dist/plugin. Go is needed only for this source build; the installed package does not need Go at runtime. If dist/plugin was supplied as a prebuilt package, skip the command.

Restart the ChatGPT desktop app, open Plugins Directory, choose Code Relay (Local) → Code Relay → Install, and start a new chat to test it. Keep the default dist/plugin output so the checked-in marketplace path remains valid. No manual marketplace JSON or codex plugin marketplace add command is required. For a fresh machine, see the local desktop install runbook for cloning the repository and installing Git, PowerShell 7, and Go 1.26+ first.

Core capabilities

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 plus a human-readable receipt for pass, fail, and blocked runs.

Development

The repository targets Go 1.26+:

go test ./...
go vet ./...
go build ./cmd/code-relay-agent
npm ci
npm test
npm run verify
./scripts/validate-contracts.ps1
./scripts/smoke-e2e.ps1

Build the bundled agent for the current platform with ./scripts/build-agent.ps1. The CLI is a developer/CI fallback; normal users install through their coding agent's MCP/plugin mechanism.

Documentation

License

Code Relay is released under the MIT License.

Install

Add Code Relay to your client. Pick the one you use.

claude mcp add code-relay-mcp -- npx -y code-relay-mcp

codex mcp add code-relay-mcp -- npx -y code-relay-mcp

amp mcp add code-relay-mcp -- npx -y code-relay-mcp

{
  "mcpServers": {
    "code-relay-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "code-relay-mcp"
      ]
    }
  }
}

Add to `claude_desktop_config.json`, then restart Claude Desktop.

{
  "mcpServers": {
    "code-relay-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "code-relay-mcp"
      ]
    }
  }
}

Add to `~/.cursor/mcp.json`, or `.cursor/mcp.json` for a single project.

code --add-mcp '{"name":"code-relay-mcp","command":"npx","args":["-y","code-relay-mcp"]}'

Or add the block manually to `.vscode/mcp.json` under `servers`.

{
  "mcpServers": {
    "code-relay-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "code-relay-mcp"
      ]
    }
  }
}

Add to `~/.codeium/windsurf/mcp_config.json`.

{
  "mcpServers": {
    "code-relay-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "code-relay-mcp"
      ]
    }
  }
}

Add to `cline_mcp_settings.json` via the MCP Servers panel.

{
  "mcpServers": {
    "code-relay-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "code-relay-mcp"
      ]
    }
  }
}

Add to `~/.gemini/settings.json`.

{
  "mcpServers": {
    "code-relay-mcp": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "code-relay-mcp"
      ],
      "tools": [
        "*"
      ]
    }
  }
}

Add to `~/.copilot/mcp-config.json`, or run `/mcp add` inside the CLI.

{
  "context_servers": {
    "code-relay-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "code-relay-mcp"
        ]
      }
    }
  }
}

Add to your Zed `settings.json`.

npx -y code-relay-mcp

Run `goose configure`, choose **Add Extension → Command-line Extension**, and paste this command.

Score

39 / 100

Incomplete

Documentation25/25
Maintenance19/25
Trust13/20
Capability0/15
Install experience12/15

Documents what it does and how to connect
Has a resolvable package or endpoint
Exposes at least one tool, prompt or resource
README has substantive content
Includes a code example
Documents its configuration
Mentions credentials or security posture
Last commit 0 days ago
Has a release history
Repository is not archived
Licensed MIT
Namespace verified in the official MCP registry
Claimed by its owner
Published under an organisation
0 tool(s) documented
Provides prompt templates
Provides resources
12 documented install method(s)
Published to a package registry
Offers a hosted endpoint — no local install

Read the full rubric →

Version history

Versions	Published
3.1.0Latest	Sep 1, 2026