Relay

Relay

Claude-only. If ANTHROPIC_BASE_URL contains z.ai, kimi.com, deepseek, or xiaomimimo, 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 GPT, Grok, GLM, Kimi, DeepSeek, or MiMo 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 (GLM/Kimi/DeepSeek/MiMo via claude -p with the model weights swapped — GLM-5.3, Kimi-K2.7-Coding, V4-Flash, MiMo-V2.5-Pro; GPT 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 — GPT and Grok Build do both (verified 2026-06-06). Re-verified 2026-06-19 for the claude-env peers by having each invoke the tools: DeepSeek does both; MiMo has native WebFetch but no live WebSearch; GLM has native WebSearch but no WebFetch. Both remaining native gaps are covered by verified Jina fallbacks, so every peer effectively has both fetch and search: a missing WebFetch falls back to the keyless Jina Reader (r.jina.ai) — or, on GLM, its own MCP web_reader — and MiMo's missing WebSearch falls back to Jina Search (s.jina.ai, end-to-end verified 2026-06-19 once JINA_API_KEY was provisioned; see Prompting Grok, GLM, Kimi, DeepSeek, and MiMo for the MiMo instruction). Kimi K2.7 Coding (via the Kimi-for-Coding plan, verified 2026-07-25) needs no Jina fallback at all: its native WebFetch and WebSearch both work (the web tools' thinking-off aux calls route to the plan's non-thinking model, which accepts them). The only constant difference from you is the model behind the harness.

relay call --name <slug> [--to <peer>] [--effort <level>] [--body-only] <<'BODY'
task
BODY

relay is in PATH. The caller is always Claude (this is a Claude-only skill); the peer defaults to GPT. Pass --to grok-build, --to glm, --to kimi, --to deepseek, or --to mimo to route elsewhere.

If a bare relay ever returns "command not found" (a sandboxed/non-zsh/reset-env shell that didn't inherit the PATH entry), re-run the identical command with the absolute install path — ~/.claude/skills/relay/scripts/relay call …. That is the whole recovery; do not reconstruct the call by hand.

All GPT, Grok, GLM, Kimi, DeepSeek, and MiMo interactions go through relay call. Do not invoke codex exec, the grok CLI, or the glm/km/ds/mm aliases directly, do not spawn agents to run the codex, grok, or claude CLI for these purposes, and do not pass model flags (-m, --model) — the model and invocation method come from the peer registry (peers.json), not the call.

Peer selection

Pick GPT by default — it's the strongest general-purpose coding agent and integrates cleanly with the relay protocol. Pick Grok Build, GLM, Kimi, DeepSeek, or MiMo for a perspective from a model trained outside both the Anthropic and OpenAI lineages, or when running /prism Parallax. Of these, only Grok Build has an effort knob (low/medium/high); GLM, Kimi, DeepSeek, and MiMo ignore --effort, so omit it for them. GLM requires GLM_PLAN_KEY_INT (a z.ai GLM Coding Plan key), Kimi requires KIMI_PLAN_KEY_CN (a Kimi-for-Coding key), DeepSeek requires DEEPSEEK_API_KEY_INT, and MiMo requires MIMO_API_KEY_INT (a MiMo pay-per-token API key) in the environment; Grok uses its own cached login (no key var).

Peer registry

Every model-family fact — transport (codex CLI vs a generic claude-env Anthropic-compatible envelope), endpoint, key variable, model id, effort knob, per-peer extras, and launcher template style — lives once in peers.json next to the script. relay and prism-launch both read it, so adding a peer that reuses an existing transport is one stanza there, not edits across the script, the prism launcher, and the docs. Two of the per-peer keys are prism-consumed, not relay-consumed: order (the standard-tier dispatch/display position) and lineage (the synthesis-weighting group — each peer is its own lineage). relay ignores them, but prism-launch derives its tier order, peershape display, and digest lineage from them, so keep them on each standard-tier stanza (a peer with no order is simply not a Prism standard tier). The claude-env peers share one code path that differs only by registry data; GPT and Grok each have their own transport. Two deliberate exceptions stay in code, not data: a brand-new transport needs its own script branch (this is how grok was added — its own headless-CLI invocation), and a new claude-env peer should also get its endpoint added to the inbound Claude-only refusal at the top of the script (a one-line safety guard that must run before the registry is loaded). Grok needs no refusal entry — it sets no ANTHROPIC_BASE_URL, and the transport-agnostic RELAY_PEER guard already blocks a dispatched grok peer from recursing. The interactive glm/km/ds/mm launchers in shell/.functions are a separate consumer and still carry their own copy — keep them in sync, with one named exception: since 2026-07-31 the relay/prism deepseek lane runs deepseek-v4-flash while the interactive ds/dsh/dsc family and Pi's pds stay on deepseek-v4-pro[1m]. That divergence is deliberate and temporary — do not "resync" it; revisit both when the official V4-Pro ships.

Common Mistakes

• Premature failure diagnosis: If a relay call was launched with run_in_background: true, do not inspect .relay files or enter the failure flow until the background task's completion notification arrives. No notification means the peer is still running.
• Wrapping relay in a subagent: Do not spawn an Agent that then calls relay inside. When the subagent completes, the platform kills its child processes — including the still-running peer CLI. Call relay directly from the main conversation with run_in_background: true instead.
• Empty heredoc body: The <<'BODY' ... BODY block must contain text — an empty body causes an immediate error.
• Missing --name: Every call requires --name — omitting it is a script error, not a peer failure.

Example

relay call --name auth-review --effort medium <<'BODY'
Review src/auth.py for security issues. Run pytest to verify.
BODY

Effort Levels

--effort applies to GPT and Grok Build. The GPT API supports none/low/medium/high/xhigh/max; relay exposes low through max, plus Codex-specific ultra orchestration. Grok Build accepts low/medium/high (both relay targets default to medium). ultra is not an OpenAI API reasoning.effort value: relay passes it through and Codex interprets it as maximum reasoning plus automatic task delegation. These are different vendors' scales, not a shared standard — a level name means what each vendor defines, so high on GPT (OpenAI, reasoning guide) and high on Grok Build (xAI, reasoning docs) are not equivalent depths, and neither vendor guarantees a fixed token progression across levels. Pick the level from the model you're calling, not by analogy to the other. DeepSeek, GLM, and Kimi run with reasoning pinned on via the registry (DeepSeek via DeepThink; GLM via reasoning_effort: max; Kimi via CLAUDE_CODE_EFFORT_LEVEL=high — K2.7 Coding is thinking-only and has no graded effort), and MiMo has no effort knob. None of them takes a graded --effort, so the flag is silently ignored or omitted on those calls.

Before raising effort, improve the prompt first — add outcome-first success criteria, stop rules, verification steps, and completeness criteria.

Prompting GPT

Before composing the prompt body, read the prompt-engineer reference — ~/.claude/skills/prompt-engineer/references/gpt.md for cross-cutting GPT-5.6 prompt patterns. If that symlink is unavailable, use the repo copy at agents/skills/prompt-engineer/references/. This is not optional — the guide contains model-specific patterns that materially affect output quality.

Lead with the outcome, not the procedure. GPT-5.6 responds best to outcome-first prompts — state the goal, success criteria, and stop rules, then let GPT pick the path. Use XML scaffolding only when a specific failure mode needs it:

• <output_contract> — when format precision matters
• <completeness_contract> — when the task has discrete items that must all be covered
• <verification_loop> — when post-change validation is required

Example:

relay call --name pool-refactor --effort medium <<'BODY'
Add connection timeouts and stale-connection recovery to src/db/pool.py.

Success criteria:
- 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

<verification_loop>
Run pytest tests/test_pool.py — all tests must pass. No new lint errors.
</verification_loop>

<output_contract>
Summary of changes, one per line, with file path and description.
</output_contract>
BODY

Prompting Grok, GLM, Kimi, DeepSeek, and MiMo

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.3, Kimi-K2.7-Coding, and Grok Build have no dedicated reference; treat them like DeepSeek.

Default to XML scaffolding (DeepSeek V4 was trained heavily on XML-tagged data; Grok, GLM, Kimi, and MiMo behave similarly). The CO-STAR sections — <context>, <objective>, <style>, <tone>, <audience>, <response_format> — 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.

MiMo live web search → Jina Search. MiMo's native WebSearch returns stale training-data, not live results — and silently (no error), so nothing auto-triggers a fallback. When a MiMo task needs current web information, state that in the prompt body and tell it to run Jina Search via Bash (JINA_API_KEY is provisioned in the peer env — end-to-end verified 2026-06-19):

curl -s 'https://s.jina.ai/<URL-ENCODED-QUERY>' -H 'Accept: application/json' -H "Authorization: Bearer $JINA_API_KEY"

Results return as JSON data[] with title, url, and full-page content. MiMo's native WebFetch works for plain URL fetches, so this fallback is only for search. Full options (headers, parsing, site-restriction) live in the jina skill.

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

relay call --to deepseek --name pool-design <<'BODY'
<context>
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.
</context>

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

<success_criteria>
- 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
</success_criteria>

<response_format>
Summary of changes first (one line per change: file path + description),
then the diffs grouped by file. Cap at 400 words excluding diffs.
</response_format>
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 <output_contract> for GPT, <response_format> for Grok/GLM/Kimi/DeepSeek/MiMo:

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
3. Fix and retry once. Correct the invocation based on the diagnosis and re-run the relay call.
4. 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 (GPT max, GLM at max, Kimi thinking, DeepSeek/MiMo DeepThink, 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 (GPT, Grok, GLM, Kimi, DeepSeek, or MiMo) 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., GPT) does not affect the others.

Utility Commands

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

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