ScuttleBot

scuttlebot / skills / scuttlebot-relay / SKILL.md
Source Blame History 191 lines
1d3caa2… lmata 1 ---
1d3caa2… lmata 2 name: scuttlebot-relay
1d3caa2… lmata 3 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.
1d3caa2… lmata 4 ---
1d3caa2… lmata 5
1d3caa2… lmata 6 # Scuttlebot Relay
1d3caa2… lmata 7
1d3caa2… lmata 8 Use this skill when the task is about relay setup or relay architecture. Do not
1d3caa2… lmata 9 invent setup commands from memory. Prefer the tracked installers and the shared
1d3caa2… lmata 10 broker contract already in this repo.
1d3caa2… lmata 11
1d3caa2… lmata 12 Installed files under `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.local/bin/`,
1d3caa2… lmata 13 and `~/.config/` are generated copies. The repo is the source of truth.
1d3caa2… lmata 14
1d3caa2… lmata 15 ## Existing runtimes
1d3caa2… lmata 16
1d3caa2… lmata 17 Pick the runtime first, then use its tracked installer and docs:
1d3caa2… lmata 18
1d3caa2… lmata 19 - Claude:
1d3caa2… lmata 20 - installer: `skills/scuttlebot-relay/scripts/install-claude-relay.sh`
1d3caa2… lmata 21 - install doc: `skills/scuttlebot-relay/install.md`
1d3caa2… lmata 22 - fleet guide: `skills/scuttlebot-relay/FLEET.md`
1d3caa2… lmata 23 - Codex:
1d3caa2… lmata 24 - installer: `skills/openai-relay/scripts/install-codex-relay.sh`
1d3caa2… lmata 25 - install doc: `skills/openai-relay/install.md`
1d3caa2… lmata 26 - fleet guide: `skills/openai-relay/FLEET.md`
1d3caa2… lmata 27 - Gemini:
1d3caa2… lmata 28 - installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
1d3caa2… lmata 29 - install doc: `skills/gemini-relay/install.md`
1d3caa2… lmata 30 - fleet guide: `skills/gemini-relay/FLEET.md`
1d3caa2… lmata 31
1d3caa2… lmata 32 When installing or reconfiguring an existing runtime:
1d3caa2… lmata 33
1d3caa2… lmata 34 1. Prefer the tracked installer script over manual edits.
1d3caa2… lmata 35 2. Default to `SCUTTLEBOT_TRANSPORT=irc` when real IRC presence matters.
1d3caa2… lmata 36 3. Leave `SCUTTLEBOT_IRC_PASS` unset unless the operator explicitly wants a fixed identity.
1d3caa2… lmata 37 4. Always set one primary control channel with `SCUTTLEBOT_CHANNEL`.
1d3caa2… lmata 38 5. Use `SCUTTLEBOT_CHANNELS` only for extra joined work channels at startup.
1d3caa2… lmata 39 6. Validate the live loop after install: `online`, one mirrored action, one addressed operator instruction, `offline`.
1d3caa2… lmata 40
1d3caa2… lmata 41 ## Channel conventions
1d3caa2… lmata 42
1d3caa2… lmata 43 Relay brokers use two channel concepts:
1d3caa2… lmata 44
1d3caa2… lmata 45 - `SCUTTLEBOT_CHANNEL`: primary control channel
1d3caa2… lmata 46 - `SCUTTLEBOT_CHANNELS`: comma-separated startup channel set, including the control channel
1d3caa2… lmata 47
1d3caa2… lmata 48 Live brokers support runtime channel control:
1d3caa2… lmata 49
1d3caa2… lmata 50 - `/channels`
1d3caa2… lmata 51 - `/join #channel`
1d3caa2… lmata 52 - `/part #channel`
1d3caa2… lmata 53
1d3caa2… lmata 54 Use the control channel for operator coordination. Join extra work channels only
1d3caa2… lmata 55 when the session needs to mirror activity there too.
e8b5616… lmata 56
e8b5616… lmata 57 ## Connection health and reconnection
e8b5616… lmata 58
e8b5616… lmata 59 All three relay binaries (`claude-relay`, `codex-relay`, `gemini-relay`) handle
e8b5616… lmata 60 `SIGUSR1` as a reconnect signal. When the relay receives `SIGUSR1` it tears down
e8b5616… lmata 61 its current IRC/HTTP session and re-establishes the connection from scratch
e8b5616… lmata 62 without restarting the process.
e8b5616… lmata 63
e8b5616… lmata 64 The `relay-watchdog` sidecar automates this:
e8b5616… lmata 65
e8b5616… lmata 66 - Reads `~/.config/scuttlebot-relay.env` (same env file the relays use).
e8b5616… lmata 67 - Polls `$SCUTTLEBOT_URL/v1/status` every 10 seconds.
e8b5616… lmata 68 - Detects server restarts (changed boot ID) and extended outages.
e8b5616… lmata 69 - Sends `SIGUSR1` to the relay process when a reconnect is needed.
e8b5616… lmata 70
e8b5616… lmata 71 Run the watchdog alongside any relay:
e8b5616… lmata 72
e8b5616… lmata 73 ```bash
e8b5616… lmata 74 relay-watchdog &
e8b5616… lmata 75 claude-relay "$@"
e8b5616… lmata 76 ```
e8b5616… lmata 77
e8b5616… lmata 78 Or use the convenience wrapper:
e8b5616… lmata 79
e8b5616… lmata 80 ```bash
e8b5616… lmata 81 skills/scuttlebot-relay/scripts/relay-start.sh claude-relay [args...]
e8b5616… lmata 82 ```
e8b5616… lmata 83
e8b5616… lmata 84 Container / fleet pattern: have the entrypoint run both processes, or use
e8b5616… lmata 85 supervisord. The watchdog exits cleanly when its parent relay exits.
e8b5616… lmata 86
e8b5616… lmata 87 ## Per-repo channel config
e8b5616… lmata 88
e8b5616… lmata 89 Drop a `.scuttlebot.yaml` in a repo root (gitignored) to override channel
e8b5616… lmata 90 settings per project:
e8b5616… lmata 91
e8b5616… lmata 92 ```yaml
e8b5616… lmata 93 # .scuttlebot.yaml
e8b5616… lmata 94 channel: my-project # auto-joins this as the control channel
e8b5616… lmata 95 channels: # additional channels joined at startup
e8b5616… lmata 96 - my-project
e8b5616… lmata 97 - design-review
e8b5616… lmata 98 ```
e8b5616… lmata 99
e8b5616… lmata 100 `channel` sets the primary control channel for the session (equivalent to
e8b5616… lmata 101 `SCUTTLEBOT_CHANNEL`). The optional `channels` list adds extra work channels
e8b5616… lmata 102 (equivalent to `SCUTTLEBOT_CHANNELS`). Values in the file override the
e8b5616… lmata 103 environment for that repo only.
1d3caa2… lmata 104
1d3caa2… lmata 105 ## Transport conventions
1d3caa2… lmata 106
1d3caa2… lmata 107 Use one broker contract for both transport modes:
1d3caa2… lmata 108
1d3caa2… lmata 109 - `SCUTTLEBOT_TRANSPORT=irc`
1d3caa2… lmata 110 - real IRC presence
1d3caa2… lmata 111 - real channel join/part semantics
1d3caa2… lmata 112 - appears in the user list and agent roster through auto-registration
1d3caa2… lmata 113 - `SCUTTLEBOT_TRANSPORT=http`
1d3caa2… lmata 114 - bridge/API transport
1d3caa2… lmata 115 - uses silent presence touches instead of visible chatter
1d3caa2… lmata 116 - useful when a direct IRC socket is not available
1d3caa2… lmata 117
1d3caa2… lmata 118 Default auth convention:
1d3caa2… lmata 119
1d3caa2… lmata 120 - broker sessions: auto-register ephemeral session nicks
1d3caa2… lmata 121 - persistent `*-agent` bots: fixed NickServ credentials when appropriate
1d3caa2… lmata 122
1d3caa2… lmata 123 ## Canonical broker contract
1d3caa2… lmata 124
1d3caa2… lmata 125 Read `skills/scuttlebot-relay/ADDING_AGENTS.md` when:
1d3caa2… lmata 126
1d3caa2… lmata 127 - adding another runtime
1d3caa2… lmata 128 - changing the shared env contract
1d3caa2… lmata 129 - changing nick/channel conventions
1d3caa2… lmata 130 - changing who owns presence, input injection, or activity mirroring
1d3caa2… lmata 131
1d3caa2… lmata 132 The shared runtime pieces are:
1d3caa2… lmata 133
1d3caa2… lmata 134 - terminal-session brokers in `cmd/*-relay/`
1d3caa2… lmata 135 - IRC-resident agents in `cmd/*-agent/`
1d3caa2… lmata 136 - shared transport layer in `pkg/sessionrelay/`
1d3caa2… lmata 137 - shared IRC bot runtime in `pkg/ircagent/`
1d3caa2… lmata 138
1d3caa2… lmata 139 ## New runtime checklist
1d3caa2… lmata 140
1d3caa2… lmata 141 For a new terminal runtime, ship this exact shape:
1d3caa2… lmata 142
1d3caa2… lmata 143 - `cmd/{runtime}-relay/main.go`
1d3caa2… lmata 144 - `skills/{runtime}-relay/install.md`
1d3caa2… lmata 145 - `skills/{runtime}-relay/FLEET.md`
1d3caa2… lmata 146 - `skills/{runtime}-relay/hooks/`
1d3caa2… lmata 147 - `skills/{runtime}-relay/scripts/install-{runtime}-relay.sh`
1d3caa2… lmata 148
1d3caa2… lmata 149 Reuse `pkg/sessionrelay/` before writing another connector by hand.
1d3caa2… lmata 150
1d3caa2… lmata 151 Match these conventions:
1d3caa2… lmata 152
1d3caa2… lmata 153 - nick format: `{runtime}-{basename}-{session}`
1d3caa2… lmata 154 - shared `SCUTTLEBOT_*` env contract
1d3caa2… lmata 155 - broker owns `online` / `offline`
1d3caa2… lmata 156 - broker owns live operator message injection
1d3caa2… lmata 157 - broker owns transport and presence
1d3caa2… lmata 158 - hooks stay as runtime-specific fallback/integration points
1d3caa2… lmata 159
1d3caa2… lmata 160 ## Examples
1d3caa2… lmata 161
1d3caa2… lmata 162 Codex:
1d3caa2… lmata 163
1d3caa2… lmata 164 ```bash
1d3caa2… lmata 165 bash skills/openai-relay/scripts/install-codex-relay.sh \
1d3caa2… lmata 166 --url http://localhost:8080 \
1d3caa2… lmata 167 --token "$(./run.sh token)" \
1d3caa2… lmata 168 --channel general \
1d3caa2… lmata 169 --transport irc
1d3caa2… lmata 170 ```
1d3caa2… lmata 171
1d3caa2… lmata 172 Gemini:
1d3caa2… lmata 173
1d3caa2… lmata 174 ```bash
1d3caa2… lmata 175 bash skills/gemini-relay/scripts/install-gemini-relay.sh \
1d3caa2… lmata 176 --url http://localhost:8080 \
1d3caa2… lmata 177 --token "$(./run.sh token)" \
1d3caa2… lmata 178 --channel general \
1d3caa2… lmata 179 --channels general,task-42 \
1d3caa2… lmata 180 --transport irc
1d3caa2… lmata 181 ```
1d3caa2… lmata 182
1d3caa2… lmata 183 Claude:
1d3caa2… lmata 184
1d3caa2… lmata 185 ```bash
1d3caa2… lmata 186 bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \
1d3caa2… lmata 187 --url http://localhost:8080 \
1d3caa2… lmata 188 --token "$(./run.sh token)" \
1d3caa2… lmata 189 --channel general \
1d3caa2… lmata 190 --transport irc
1d3caa2… lmata 191 ```

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button