ScuttleBot

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

Keyboard Shortcuts

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