Codex Relay Fleet Launch

This is the rollout guide for making local Codex terminal sessions IRC-visible and operator-addressable through scuttlebot.

Codex and Gemini are the canonical terminal-broker reference implementations in this repo. The normative path and convention contract lives in ../scuttlebot-relay/ADDING_AGENTS.md.

Source of truth: - installer: scripts/install-codex-relay.sh - broker: ../../cmd/codex-relay/main.go - shared connector: ../../pkg/sessionrelay/ - dev wrapper: scripts/codex-relay.sh - hooks: hooks/scuttlebot-post.sh, hooks/scuttlebot-check.sh - runtime docs: install.md, hooks/README.md - canonical relay contract: ../scuttlebot-relay/ADDING_AGENTS.md

Installed files under ~/.codex/, ~/.local/bin/, and ~/.config/ are generated copies. Point other engineers and agents at the repo docs and installer, not at one person's home directory.

Runtime prerequisites: - codex - go - curl - jq

Canonical pattern

Future terminal runtimes should copy this shape: - broker entrypoint in cmd/{runtime}-relay/main.go - tracked installer in skills/{runtime}-relay/scripts/install-{runtime}-relay.sh - rollout guide in skills/{runtime}-relay/FLEET.md - install primer in skills/{runtime}-relay/install.md - runtime hook docs in skills/{runtime}-relay/hooks/README.md - shared transport and presence logic in pkg/sessionrelay/

Ownership conventions: - the broker owns online / offline - the broker owns addressed operator message injection into the live terminal - the broker owns outbound activity and assistant-message mirroring when the runtime exposes a reliable session log - hooks remain the pre-action fallback and non-broker compatibility layer

What this gives you

For each local Codex session launched through codex-relay: - a stable nick: codex-{repo}-{session} - immediate online post when the session starts - mirrored tool activity from the active session log - mirrored assistant messages from the active session log - continuous addressed IRC input injection into the live terminal session - explicit pre-tool fallback interrupts before the next action - offline post on exit

Transport choice: - SCUTTLEBOT_TRANSPORT=http keeps the bridge/API path and now uses presence heartbeats - SCUTTLEBOT_TRANSPORT=irc logs the session nick directly into Ergo for real presence

This is the production control path for a human-operated Codex terminal. If you want an always-on IRC-resident bot instead, use cmd/codex-agent.

One-machine install

Run from the repo checkout:

bash skills/openai-relay/scripts/install-codex-relay.sh \
  --url http://localhost:8080 \
  --token "$(./run.sh token)" \
  --channel general

Then launch:

~/.local/bin/codex-relay

Fleet rollout

For multiple workstations or VM images:

1. Distribute this repo revision.
2. Run the tracked installer on each machine.
3. Launch Codex through ~/.local/bin/codex-relay instead of codex.

Example:

bash skills/openai-relay/scripts/install-codex-relay.sh \
  --url http://scuttlebot.example.com:8080 \
  --token "$SCUTTLEBOT_TOKEN" \
  --channel fleet \
  --transport irc \
  --irc-addr scuttlebot.example.com:6667

If you need hooks present but inactive until the server is live:

bash skills/openai-relay/scripts/install-codex-relay.sh --disabled

Later, re-enable by editing ~/.config/scuttlebot-relay.env or rerunning:

bash skills/openai-relay/scripts/install-codex-relay.sh --enabled

What the installer changes

The installer is intentionally narrow. It: - copies the tracked hook scripts into ~/.codex/hooks/ - builds and installs codex-relay into ~/.local/bin/ - merges required hook entries into ~/.codex/hooks.json - ensures features.codex_hooks = true in ~/.codex/config.toml - writes SCUTTLEBOT_* settings into ~/.config/scuttlebot-relay.env - defaults IRC auth to auto-registration by removing any stale SCUTTLEBOT_IRC_PASS - keeps one backup copy as *.bak before overwriting an existing installed file

It does not: - replace the real codex binary in PATH - force a fixed nick across sessions - require IRC to be up at install time

Useful shared env knobs: - SCUTTLEBOT_TRANSPORT=http|irc selects the connector backend - SCUTTLEBOT_CHANNEL is the primary control channel - SCUTTLEBOT_CHANNELS=general,task-42 seeds extra startup work channels - SCUTTLEBOT_IRC_ADDR=127.0.0.1:6667 sets the real IRC address when transport is irc - SCUTTLEBOT_IRC_PASS=... uses a fixed NickServ password instead of auto-registration; leave it unset for the default broker convention - SCUTTLEBOT_IRC_DELETE_ON_CLOSE=0 keeps auto-registered session nicks after clean exit - SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1 interrupts the live Codex session only when Codex appears busy; idle sessions are injected directly and auto-submitted - SCUTTLEBOT_POLL_INTERVAL=2s controls how often the broker checks for new addressed IRC messages - SCUTTLEBOT_PRESENCE_HEARTBEAT=60s controls HTTP presence touches; set 0 to disable - SCUTTLEBOT_MIRROR_REASONING=1 mirrors Codex reasoning blocks to IRC, prefixed with 💭 (off by default) - SCUTTLEBOT_ACTIVITY_VIA_BROKER=1 tells scuttlebot-post.sh to stay quiet so broker-launched sessions do not duplicate activity posts

Installer auth knobs: - default or --auto-register: scrub SCUTTLEBOT_IRC_PASS from the shared env file and let the broker auto-register ephemeral session nicks - --irc-pass <passphrase>: persist a fixed NickServ password in the shared env file

Live channel commands: - /channels - /join #task-42 - /part #task-42

Operator workflow

1. Watch the configured channel in scuttlebot.
2. Wait for a new codex-{repo}-{session} online post.
3. Mention that nick when you need to steer the session.
4. cmd/codex-relay injects the addressed IRC message into the live terminal session.
5. The pre-tool hook still blocks on the next Bash|Edit|Write if needed.

Examples:

operator: codex-scuttlebot-a1b2c3d4 stop and re-read bridge.go
operator: codex-scuttlebot-a1b2c3d4 wrong file, inspect policies.go first

Ambient channel chat does not block the loop. Only explicit nick mentions do.

When IRC/scuttlebot is down

Disable without uninstalling:

SCUTTLEBOT_HOOKS_ENABLED=0 ~/.local/bin/codex-relay

Or persist the disabled state in the shared env file:

bash skills/openai-relay/scripts/install-codex-relay.sh --disabled

The hooks and broker soft-fail if the HTTP API is unavailable. Codex still runs; you just lose the IRC coordination layer until the server comes back.

Adding more runtimes

Do not fork the protocol. Reuse the same control contract: - post activity out after each action - mirror assistant progress and replies when the runtime exposes them - accept addressed operator instructions back in before the next action - use stable, human-addressable session nicks - keep the repo as the source of truth

The shared authoring contract lives in ../scuttlebot-relay/ADDING_AGENTS.md.