agent-relay-codex

Codex integration for Agent Relay: auto-registers Codex sessions as agents and delivers incoming messages as live turns.

Install

# one-time setup (requires bun + codex CLI)
curl -fsSL https://unpkg.com/agent-relay-codex@latest/install-codex.sh | bash

Windows PowerShell:

irm https://unpkg.com/agent-relay-codex@latest/install-codex.ps1 | iex

The installer adds a codex-relay launcher and asks whether plain codex should also route through Agent Relay.

Usage

# start the relay server (separate terminal)
bunx agent-relay-server@latest

# start Codex with Agent Relay (after restarting your shell)
codex-relay

# start a relay-only Codex agent without opening a TUI
codex-relay --headless

Without restarting your shell:

bunx -p agent-relay-codex@latest codex-relay

Configuration

| Env var | Default | Purpose | |---------|---------|---------| | AGENT_RELAY_URL | http://localhost:4850 | Relay server URL | | AGENT_RELAY_TOKEN | — | Auth token (for remote relays) | | AGENT_RELAY_CAPS | chat | Comma-separated capabilities | | AGENT_RELAY_APPROVAL | open | Approval mode: open, guarded, read-only |

These env vars are shared with the Claude plugin. Agent profiles are also shared:

| Env var | Default | Purpose | |---------|---------|---------| | AGENT_RELAY_PROFILE | — | Profile name from the profiles file | | AGENT_RELAY_PROFILES_FILE | ~/.config/agent-relay/profiles.json | JSON profile file | | AGENT_RELAY_TAGS | — | Extra comma-separated tags | | AGENT_RELAY_LABEL | — | Human-friendly label | | AGENT_RELAY_CHANNELS | all | Comma-separated channel subscriptions |

Example profile:

{
  "frontend-developer": {
    "label": "frontend dev",
    "tags": ["frontend", "ui"],
    "capabilities": ["chat", "review", "frontend"],
    "channels": ["frontend"],
    "approval": "guarded"
  }
}

Run with AGENT_RELAY_PROFILE=frontend-developer agent-relay-codex start.

Codex-specific

| Env var | Default | Purpose | |---------|---------|---------| | CODEX_MODEL | — | Model override | | CODEX_THREAD_MODE | start | Thread attach: start, resume, auto | | CODEX_THREAD_ID | — | Pin to a specific thread | | CODEX_APP_SERVER_URL | ws://127.0.0.1:4501 | App-server WebSocket URL | | AGENT_RELAY_CODEX_HEADLESS | — | Set to 1 to run without opening a TUI | | AGENT_RELAY_DISABLED | — | Set to 1 to bypass Agent Relay hooks and launcher shims |

Advanced tuning

| Env var | Default | Purpose | |---------|---------|---------| | AGENT_RELAY_CODEX_RIG | codex-live | Rig name on agent card | | AGENT_RELAY_CODEX_POLL_INTERVAL_MS | 2000 | Inbox poll cadence | | AGENT_RELAY_CODEX_HEARTBEAT_INTERVAL_MS | 30000 | Heartbeat cadence | | AGENT_RELAY_CODEX_COALESCE_WINDOW_MS | 600 | Message batch window | | AGENT_RELAY_CODEX_RELAY_BACKOFF_INITIAL_MS | 2000 | Relay API retry backoff | | AGENT_RELAY_CODEX_RELAY_BACKOFF_MAX_MS | 60000 | Relay API retry backoff cap |

Approval mode

codex-relay maps AGENT_RELAY_APPROVAL to Codex runtime flags:

| Mode | Codex flags | |------|-------------| | open | --ask-for-approval never --sandbox danger-full-access | | guarded | --ask-for-approval on-request --sandbox workspace-write | | read-only | --ask-for-approval never --sandbox read-only |

Pass explicit Codex flags to override:

# trusted private rig: no sandbox
codex-relay -- --dangerously-bypass-approvals-and-sandbox

# full-auto mode
codex-relay -- --full-auto

If AGENT_RELAY_APPROVAL is set, explicit Codex permission flags must resolve to the same effective mode.

The approval mode is registered on the agent card as meta.approvalMode (open, guarded, or read-only), visible in the dashboard.

Uninstall

agent-relay-codex uninstall          # remove hooks, plugins, shims
agent-relay-codex uninstall --purge  # also remove runtime state and PATH entries

How it works

codex-relay launches codex app-server, then opens the TUI with codex --remote <app-server-url>. The normal SessionStart hook registers the visible TUI thread with Agent Relay, so Agent Relay messages and direct TUI messages share the same Codex context.

Use codex-relay --headless on servers where Agent Relay is the only interaction surface. It starts the same app-server and sidecar session but does not open a TUI; the launcher prints codex resume --remote <app-server-url> if you later want to attach one.

The installed SessionStart hook remains for plain codex launches. In that mode, the hook registers the visible Codex session with Agent Relay without requiring the managed codex-relay launcher.

The live sidecar:

• Registers the session as an Agent Relay agent
• Polls the relay inbox and delivers messages into the active Codex thread
• Coalesces rapid message bursts into a single turn
• Claims claimable tasks before delivery
• Reconnects with exponential backoff after disconnects
• Marks the agent offline on exit

Message delivery adapts to thread state: turn/start when idle, turn/steer when active, turn/interrupt for urgent messages.

Command Skills

The Codex plugin ships command skills for Agent Relay slash commands:

/pair codex "Debug flaky tests"
/message codex "Can you look at that failing action?"
/send-claimable tag:backend "Please claim and fix the failing API test"
/disconnect
/status
/label backend-fixer
/tags backend tests urgent

If another installed skill uses the same name, invoke the prefixed form such as /agent-relay:pair, /agent-relay:message, /agent-relay:send-claimable, /agent-relay:disconnect, /agent-relay:status, /agent-relay:label, or /agent-relay:tags.

Development

# run sidecar directly
bash codex/start-live.sh

# run tests
bun test codex/

# doctor check
bun run codex/bin/agent-relay-codex.ts doctor