- the repo copies in this directory and `../scripts/`
31
- not the installed copies under `~/.gemini/` or `~/.local/bin/`
32
33
## What they do
34
35
`scuttlebot-post.sh`
36
- runs on Gemini CLI `AfterTool`
37
- posts a one-line activity summary into a scuttlebot channel
38
- remains the primary Gemini activity path today, even when launched through `gemini-relay`
39
- returns valid JSON success output (`{}`), which Gemini CLI expects for hook success
40
41
`scuttlebot-check.sh`
42
- runs on Gemini CLI `BeforeTool`
43
- fetches recent channel messages from scuttlebot
44
- ignores bots and agent status nicks
45
- blocks only when a human explicitly mentions this session nick
46
- returns valid JSON success output (`{}`) when no block is needed
47
48
`scuttlebot-after-agent.sh`
49
- runs on Gemini CLI `AfterAgent`
50
- posts the final assistant reply for each completed turn into scuttlebot
51
- normalizes whitespace and splits long replies into IRC-safe lines
52
- returns valid JSON success output (`{}`), which Gemini CLI expects for hook success
53
54
With the broker plus hooks together, you get the current control loop:
55
1. `cmd/gemini-relay` posts `online`.
56
2. The operator mentions the Gemini session nick.
57
3. `cmd/gemini-relay` injects that IRC message into the live terminal session immediately using bracketed paste, so operator text is treated literally instead of as Gemini keyboard shortcuts.
58
4. `scuttlebot-check.sh` still blocks before the next tool action if needed.
Install the compiled broker if you want startup/offline presence plus continuous
202
IRC input injection:
203
204
```bash
205
mkdir -p ~/.local/bin
206
go build -o ~/.local/bin/gemini-relay ./cmd/gemini-relay
207
chmod +x ~/.local/bin/gemini-relay
208
```
209
210
Launch with:
211
212
```bash
213
~/.local/bin/gemini-relay
214
```
215
216
## Message filtering semantics
217
218
The check hook only surfaces messages that satisfy all of the following:
219
- newer than the last check for this session
220
- not posted by this session nick
221
- not posted by known service bots
222
- not posted by `claude-*`, `codex-*`, or `gemini-*` status nicks
223
- explicitly mention this session nick
224
225
Ambient channel chat must not halt a live tool loop.
226
227
## Operational notes
228
229
- `cmd/gemini-relay` can use either the HTTP bridge API or a real IRC socket.
230
- `SCUTTLEBOT_CHANNEL` is the primary control channel; `SCUTTLEBOT_CHANNELS` is the startup channel set.
231
- `/channels`, `/join #channel`, and `/part #channel` change the live session channel set without rewriting the shared env file.
232
- `SCUTTLEBOT_TRANSPORT=irc` gives the live session a true IRC presence; `SCUTTLEBOT_IRC_PASS` skips auto-registration if you already manage the NickServ account yourself.
233
- `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` keeps quiet HTTP-mode sessions in the active user list without visible chatter.
234
- `SCUTTLEBOT_CHANNEL_STATE_FILE` is the broker-written override file that keeps hooks aligned with live channel joins and parts.
235
- Gemini CLI expects hook success responses on `stdout` to be valid JSON; these relay hooks emit `{}` on success and structured deny JSON on blocks.
236
- Gemini CLI built-in tool names are things like `run_shell_command`, `read_file`, and `write_file`; the activity hook summarizes those native names.
237
- Gemini outbound mirroring is still hook-owned today: `AfterTool` covers tool activity and `AfterAgent` covers final assistant replies. That is the main behavioral difference from `codex-relay`, which mirrors activity from a richer session log.
238
- `scuttlebot-after-agent.sh` compacts whitespace, splits replies into IRC-safe chunks, and caps the number of posts so large responses and failure payloads stay under Gemini's hook timeout.
239
- `SCUTTLEBOT_AFTER_AGENT_MAX_POSTS` defaults to `6`; `SCUTTLEBOT_AFTER_AGENT_CHUNK_WIDTH` defaults to `360`.
240
- If scuttlebot is down or unreachable, the hooks soft-fail and return quickly.
241
- `SCUTTLEBOT_HOOKS_ENABLED=0` disables all Gemini relay hooks explicitly.
242
- They should remain in the repo as installable reference files.
243
- Do not bake tokens into the scripts. Use environment variables.