relay

Imported from RA1NM4KER/agent-relay (crates/relay-cli/assets/codex/relay/SKILL.md). Install upstream with npx skills add RA1NM4KER/agent-relay --skill relay. Copyright stays with the author.

Use the installed Relay CLI to answer from actual state. Codex invokes this skill with $relay; /relay and /relay:doctor are Claude commands, not Codex commands.

Relay-managed Codex terminals supply RELAY_EXECUTABLE, RELAY_CONFIG_ROOT, RELAY_STATE_ROOT, RELAY_PROJECT_DIR, and RELAY_SESSION_ID. Check that all five are nonempty before running the commands below. If absent, explain that the conversation has no verified Relay terminal context and suggest relay doctor in a terminal in the project. Do not guess a session or owner from the working directory, profile name, or conversation text.

Choose the command matching the request (default: status). Use the shell tool and preserve the quoted environment variables as individual arguments:

"$RELAY_EXECUTABLE" --config-root "$RELAY_CONFIG_ROOT" --state-root "$RELAY_STATE_ROOT" doctor --project "$RELAY_PROJECT_DIR"
"$RELAY_EXECUTABLE" --config-root "$RELAY_CONFIG_ROOT" --state-root "$RELAY_STATE_ROOT" status --project "$RELAY_PROJECT_DIR"
"$RELAY_EXECUTABLE" --config-root "$RELAY_CONFIG_ROOT" --state-root "$RELAY_STATE_ROOT" why --project "$RELAY_PROJECT_DIR" --session "$RELAY_SESSION_ID"
"$RELAY_EXECUTABLE" --config-root "$RELAY_CONFIG_ROOT" --state-root "$RELAY_STATE_ROOT" history --project "$RELAY_PROJECT_DIR" --session "$RELAY_SESSION_ID"

Report the relevant CLI output concisely. Doctor exit code 1 with a readiness report means not ready, not an execution failure. Status lists multiple conversations: identify this one using RELAY_SESSION_ID, not merely the most recently active session. Never invent health, trust acceptance, quota, or a successful handoff. Report a sandbox denial as a denial.

For switching to a named profile, never run relay switch inside the current agent shell directly: it is not the same process as the one Relay is supervising, and stopping it mid-command would be running the switch's own kill target. Instead ask the supervising Relay process itself to do it, over the same control channel Claude's in-agent switch already uses:

"$RELAY_EXECUTABLE" --json --config-root "$RELAY_CONFIG_ROOT" --state-root "$RELAY_STATE_ROOT" switch-request <requested-profile> --project "$RELAY_PROJECT_DIR" --session "$RELAY_SESSION_ID"

This prints a JSON envelope; read data.outcome:

• "answered" — the supervisor decided. Report data.message to the user verbatim (this is the actual accept/refuse result, data.ok true or false); if accepted, the supervising terminal reopens the conversation on the new profile in a moment, no further action needed.

• "no_supervisor", "stale_session", "unreachable", or "timeout" — no verified Relay supervisor could be reached (rare: e.g. relay resume/relay codex was not what started this terminal). Fall back: show the user a shell-quoted command to run in another terminal instead, using the actual environment values for executable, roots, project and session:

  <relay> --config-root <config> --state-root <state> switch <requested-profile> --project-dir <project> --session <session> --no-attach

The interactive profile picker (no specific target named) only exists in a real terminal — when the user wants to choose rather than name a profile, go straight to the manual fallback above with the profile omitted, not switch-request (which always requires one). Do not edit trust settings, accept prompts, change permissions, install integrations, or mutate Relay state as part of a health/status request.