name: scuttlebot-relay description: Install, configure, or extend the shared scuttlebot relay brokers for Claude, Codex, Gemini, and future runtimes. Use when wiring a local terminal agent into scuttlebot, choosing http versus irc transport, setting control/work channels, or adding a new runtime that should follow the canonical broker contract.

Scuttlebot Relay

Use this skill when the task is about relay setup or relay architecture. Do not invent setup commands from memory. Prefer the tracked installers and the shared broker contract already in this repo.

Installed files under ~/.claude/, ~/.codex/, ~/.gemini/, ~/.local/bin/, and ~/.config/ are generated copies. The repo is the source of truth.

Existing runtimes

Pick the runtime first, then use its tracked installer and docs:

Claude:
installer: skills/scuttlebot-relay/scripts/install-claude-relay.sh
install doc: skills/scuttlebot-relay/install.md
fleet guide: skills/scuttlebot-relay/FLEET.md
Codex:
installer: skills/openai-relay/scripts/install-codex-relay.sh
install doc: skills/openai-relay/install.md
fleet guide: skills/openai-relay/FLEET.md
Gemini:
installer: skills/gemini-relay/scripts/install-gemini-relay.sh
install doc: skills/gemini-relay/install.md
fleet guide: skills/gemini-relay/FLEET.md

When installing or reconfiguring an existing runtime:

Prefer the tracked installer script over manual edits.
Default to SCUTTLEBOT_TRANSPORT=irc when real IRC presence matters.
Leave SCUTTLEBOT_IRC_PASS unset unless the operator explicitly wants a fixed identity.
Always set one primary control channel with SCUTTLEBOT_CHANNEL.
Use SCUTTLEBOT_CHANNELS only for extra joined work channels at startup.
Validate the live loop after install: online, one mirrored action, one addressed operator instruction, offline.

Channel conventions

Relay brokers use two channel concepts:

SCUTTLEBOT_CHANNEL: primary control channel
SCUTTLEBOT_CHANNELS: comma-separated startup channel set, including the control channel

Live brokers support runtime channel control:

/channels
/join #channel
/part #channel

Use the control channel for operator coordination. Join extra work channels only when the session needs to mirror activity there too.

Connection health and reconnection

All three relay binaries (claude-relay, codex-relay, gemini-relay) handle SIGUSR1 as a reconnect signal. When the relay receives SIGUSR1 it tears down its current IRC/HTTP session and re-establishes the connection from scratch without restarting the process.

The relay-watchdog sidecar automates this:

Reads ~/.config/scuttlebot-relay.env (same env file the relays use).
Polls $SCUTTLEBOT_URL/v1/status every 10 seconds.
Detects server restarts (changed boot ID) and extended outages.
Sends SIGUSR1 to the relay process when a reconnect is needed.

Run the watchdog alongside any relay:

relay-watchdog &
claude-relay "$@"

Or use the convenience wrapper:

skills/scuttlebot-relay/scripts/relay-start.sh claude-relay [args...]

Container / fleet pattern: have the entrypoint run both processes, or use supervisord. The watchdog exits cleanly when its parent relay exits.

Per-repo channel config

Drop a .scuttlebot.yaml in a repo root (gitignored) to override channel settings per project:

# .scuttlebot.yaml
channel: my-project          # auto-joins this as the control channel
channels:                     # additional channels joined at startup
  - my-project
  - design-review

channel sets the primary control channel for the session (equivalent to SCUTTLEBOT_CHANNEL). The optional channels list adds extra work channels (equivalent to SCUTTLEBOT_CHANNELS). Values in the file override the environment for that repo only.

Transport conventions

Use one broker contract for both transport modes:

SCUTTLEBOT_TRANSPORT=irc
real IRC presence
real channel join/part semantics
appears in the user list and agent roster through auto-registration
SCUTTLEBOT_TRANSPORT=http
bridge/API transport
uses silent presence touches instead of visible chatter
useful when a direct IRC socket is not available

Default auth convention:

broker sessions: auto-register ephemeral session nicks
persistent *-agent bots: fixed NickServ credentials when appropriate

Canonical broker contract

Read skills/scuttlebot-relay/ADDING_AGENTS.md when:

adding another runtime
changing the shared env contract
changing nick/channel conventions
changing who owns presence, input injection, or activity mirroring

The shared runtime pieces are:

terminal-session brokers in cmd/*-relay/
IRC-resident agents in cmd/*-agent/
shared transport layer in pkg/sessionrelay/
shared IRC bot runtime in pkg/ircagent/

New runtime checklist

For a new terminal runtime, ship this exact shape:

cmd/{runtime}-relay/main.go
skills/{runtime}-relay/install.md
skills/{runtime}-relay/FLEET.md
skills/{runtime}-relay/hooks/
skills/{runtime}-relay/scripts/install-{runtime}-relay.sh

Reuse pkg/sessionrelay/ before writing another connector by hand.

Match these conventions:

nick format: {runtime}-{basename}-{session}
shared SCUTTLEBOT_* env contract
broker owns online / offline
broker owns live operator message injection
broker owns transport and presence
hooks stay as runtime-specific fallback/integration points

Examples

Codex:

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

Gemini:

bash skills/gemini-relay/scripts/install-gemini-relay.sh \
  --url http://localhost:8080 \
  --token "$(./run.sh token)" \
  --channel general \
  --channels general,task-42 \
  --transport irc

Claude:

bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \
  --url http://localhost:8080 \
  --token "$(./run.sh token)" \
  --channel general \
  --transport irc

ScuttleBot