Relay

Relay

Claude-only. If ANTHROPIC_BASE_URL contains deepseek, xiaomimimo, or z.ai, this skill is unavailable — stop and tell the user: "relay is Claude-only; a non-Claude session cannot orchestrate other models." The relay script also refuses at the shell layer.

Call Codex, DeepSeek, MiMo, GLM, or Grok like a function: one command generates the request, invokes the peer, and prints the response.

> The peer is a full agent in the Claude Code harness — not a stateless API call. Relay invokes each peer through its registered transport (DeepSeek/MiMo/GLM via claude -p with the model weights swapped — V4-Pro, MiMo-V2.5-Pro, GLM-5.2; Codex via codex exec; Grok via its own grok CLI), so the peer has your core tools — Bash, file read/write, Grep/Glob, subagents, multi-step agentic loops. It can see this repo, run commands, and verify its own work; delegate file I/O and shell work directly. Do not treat it as a one-shot completion that "can't see the codebase." Web tools (WebFetch/WebSearch) are registered on every peer and broadly work — verified 2026-06-06: Codex and both Grok tiers do both; the only gaps are DeepSeek's WebFetch (400 thinking options ... reasoning_effort under its forced max effort) and MiMo's WebSearch (no live search), and each of those two still has the other web tool. So every peer can reach the web — treat browsing as available, not a per-call unknown to re-verify. The only constant difference from you is the model behind the harness.

relay call --name  [--to ] [--effort ] [--body-only] ` — when format precision matters
- `` — when the task has discrete items that must all be covered
- `` — when post-change validation is required

**Example:**

```bash
relay call --name pool-refactor --effort medium 
Run pytest tests/test_pool.py — all tests must pass. No new lint errors.

Summary of changes, one per line, with file path and description.

BODY

Prompting DeepSeek, MiMo, GLM, and Grok

These are all independent (non-Anthropic/OpenAI) models that respond well to XML-scaffolded, structured prompts. Before composing a DeepSeek prompt body, read ~/.claude/skills/relay/references/deepseek.md (symlinked to the prompt-engineer reference) — it covers the CO-STAR framework, XML scaffolding conventions, thinking-mode quirks, and DeepThink failure modes. This is not optional — the guide contains model-specific patterns that materially affect output quality. MiMo-V2.5-Pro, GLM-5.2, and Grok (both models) have no dedicated reference; treat them like DeepSeek.

Default to XML scaffolding (DeepSeek V4 was trained heavily on XML-tagged data; MiMo, GLM, and Grok behave similarly). The CO-STAR sections — `, , , , , — give the cleanest results for non-trivial tasks. Use positive framing ("include X") over negative constraints ("don't omit X"). Aside from Grok Build's --effort` flag, their thinking is always on — so keep system-style meta-instructions out of the prompt body; they degrade under long system prompts. Lead with the outcome and success criteria, then let the model pick the path.

Example (swap --to deepseek for --to mimo, --to glm, --to grok-build, or --to grok-composer to route elsewhere — the prompt shape is identical):

relay call --to deepseek --name pool-design 
We're hardening src/db/pool.py before a SOC 2 audit. Codebase is Python 3.12 +
FastAPI. Tests live in tests/test_pool.py and run under pytest.

Add connection timeouts and stale-connection recovery to src/db/pool.py.

- ConnectionPool accepts a timeout_seconds parameter at construction
- stale connections are auto-reconnected on use
- a reclaim_stale() method exists for explicit cleanup
- existing callers keep working without changes
- pytest tests/test_pool.py passes; no new lint errors

Summary of changes first (one line per change: file path + description),
then the diffs grouped by file. Cap at 400 words excluding diffs.

BODY

Calibration handoff

For judgment tasks — analysis, review, design, research, second opinions — ask the peer to end its answer with a reasons-based calibration block, then act on it when the response returns. Skip it for mechanical or code-changing calls (run-a-command, apply-a-defined-change): there the trust signal is tests, diffs, and the verify: frontmatter, not a self-report. Don't ask for a number — verbalized confidence from these models is poorly calibrated (clusters at round numbers, skews overconfident), so a % or High/Med/Low manufactures false precision the orchestrator can't discount.

Add to the prompt body — inside ` for Codex, ` for DeepSeek/MiMo/GLM/Grok:

End with a ## Calibration block:
- Key assumptions: 1-3 the answer rests on ("none material" only if true)
- Most likely wrong because: the strongest failure mode, missing info, or counterargument
- Would change my conclusion: the specific fact, test, or counterexample that would flip it
- Verify before acting: specific current/high-stakes claims to check ("none" for pure reasoning)

No numeric %, probability, or High/Medium/Low label — this block is for routing and verification, not a calibrated probability.

On return, use it — otherwise it is decoration. Verify the listed claims before passing the answer up; re-query with corrected context if a Key assumption conflicts with what you know; seek a tie-breaker (another peer or /prism) if "Most likely wrong because" attacks the core conclusion. Ignore any self-confidence score a peer volunteers anyway — the assumptions and failure mode are the signal, not a self-graded number.

Output

The script prints the response file content to stdout. The response has YAML frontmatter followed by free-form markdown:

• Frontmatter: relay, re, from, to, status (done | error), verify (pass | fail | skip)
• Body: findings, changes, reasoning — free-form markdown below the frontmatter fence

Use --body-only to strip the frontmatter and get just the markdown body.

Request and response files are saved in .relay/ (auto-gitignored). Peer stderr is logged to a .log sidecar file alongside the request. Never read the .log file — it contains the peer's full stderr output, which is extremely long and token-heavy. Only inspect the .res.md response file.

When a relay call fails

You must diagnose and retry — do not report failure to the user without attempting a fix first.

Background-task guard: If the relay call was launched with run_in_background: true, this diagnosis flow applies only after the background task's completion notification has arrived. Relay calls take significantly longer than subagents — this is normal, not a failure. Until the completion notification arrives, the call is in progress and healthy. Do not read logs or check for the response file.

When a completed relay call reports a missing response file, the peer failed before producing output. Each call generates a new request ID, so retrying does not re-execute previous attempts.

1. Check the Bash output. The relay script prints diagnostic information (exit code, error summary) to stdout/stderr. Use this — visible in the Bash tool result — to identify the cause. Do not read the .log sidecar file — full stderr, token-heavy.
2. Diagnose. Common causes and fixes:

• Peer binary not found → verify the peer CLI is installed and in PATH
• Empty body / malformed heredoc → verify the heredoc has content and a matching terminator
• Peer exited non-zero but response file exists → not a failure; read the response file

1. Fix and retry once. Correct the invocation based on the diagnosis and re-run the relay call.
2. If the retry also fails, report the failure to the user with the diagnosed cause from the Bash output.

The first failure is information, not a stop signal.

Async / Parallel

When you have independent subagent work alongside a relay call, never block on relay while subagents wait (or vice versa). Run everything concurrently:

Background the Bash call: Use run_in_background: true on the Bash tool so the relay call runs concurrently with your subagents. The platform sends a completion notification when the background task finishes — do not poll, do not inspect .relay files, and do not enter the failure diagnosis flow before that notification arrives.

Give it a generous timeout. Relay peers are full agents and can run long (Codex xhigh, DeepSeek/MiMo DeepThink, GLM at max, Grok at high routinely take many minutes). A Bash-tool timeout that fires mid-run kills the peer and wastes every token it already spent — favor completion over a tight bound. Set timeout: 3600000 (60 min) on the backgrounded Bash call; relay has no internal per-call cap, so this outer timeout is the only bound.

Rule: Launch relay calls and subagents concurrently. Never serialize independent work.

Never wrap relay in a subagent. If an Agent task calls relay with run_in_background: true, the subagent will complete before the peer (Codex, DeepSeek, MiMo, GLM, or Grok) finishes, and the platform will kill the orphaned peer process. Always call relay from the main conversation. If a subagent must call relay (e.g., the skill was invoked before you could prevent it), the Bash call must run in foreground — omit run_in_background so the subagent blocks until the peer replies.

Prism / Parallax

When Relay is used as the Parallax transport inside Prism, the relay call receives the same full question and same context as every local reviewer — only the lens (weighing posture) differs. Do not narrow the prompt for the Parallax agent. Prism dispatches each parallax tier independently — the relay calls run concurrently as separate Bash invocations.

Launch each relay Bash call with run_in_background: true in the same parallel dispatch step as the local reviewer subagents. Do not wrap Relay itself in another subagent layer.

If a Parallax relay call fails (after its background completion notification has arrived), treat it as a recoverable transport problem. Check the relay script's Bash output for the diagnosed cause, fix the invocation, and retry once before declaring that peer unavailable — never read the .log sidecar (full stderr, token-heavy). A failure of one peer (e.g., Codex) does not affect the others.

Utility Commands

relay --help and relay --version print usage and version info.

--to accepts codex (default), deepseek, mimo, glm, grok-build, or grok-composer. There is no relay-to-Claude direction — Claude is the sole caller in this protocol.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chrisliu298
• Source: chrisliu298/relay
• License: MIT

Install and usage instructions live in the source repository linked above.