ScuttleBot

scuttlebot / skills / gemini-relay / FLEET.md
Source Rendered
Blame History Raw 192 lines
1
# Gemini Relay Fleet Launch
2
3
This is the rollout guide for making local Gemini CLI terminal sessions IRC-visible and
4
operator-addressable through scuttlebot.
5
6
Gemini and Codex are the canonical terminal-broker reference implementations in
7
this repo. The normative path and convention contract lives in
8
[`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md).
9
10
Source of truth:
11
- installer: [`scripts/install-gemini-relay.sh`](scripts/install-gemini-relay.sh)
12
- broker: [`../../cmd/gemini-relay/main.go`](../../cmd/gemini-relay/main.go)
13
- shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
14
- hooks: [`hooks/scuttlebot-post.sh`](hooks/scuttlebot-post.sh), [`hooks/scuttlebot-check.sh`](hooks/scuttlebot-check.sh)
15
- reply hook: [`hooks/scuttlebot-after-agent.sh`](hooks/scuttlebot-after-agent.sh)
16
- runtime docs: [`install.md`](install.md), [`hooks/README.md`](hooks/README.md)
17
- canonical relay contract: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
18
19
Installed files under `~/.gemini/`, `~/.local/bin/`, and `~/.config/` are generated
20
copies. Point other engineers and agents at the repo docs and installer, not at one
21
person's home directory.
22
23
Runtime prerequisites:
24
- `gemini`
25
- `go`
26
- `curl`
27
- `jq`
28
29
## Canonical pattern
30
31
Future terminal runtimes should copy this shape:
32
- broker entrypoint in `cmd/{runtime}-relay/main.go`
33
- tracked installer in `skills/{runtime}-relay/scripts/install-{runtime}-relay.sh`
34
- rollout guide in `skills/{runtime}-relay/FLEET.md`
35
- install primer in `skills/{runtime}-relay/install.md`
36
- runtime hook docs in `skills/{runtime}-relay/hooks/README.md`
37
- shared transport and presence logic in `pkg/sessionrelay/`
38
39
Ownership conventions:
40
- the broker owns `online` / `offline`
41
- the broker owns addressed operator message injection into the live terminal
42
- the broker owns transport selection and presence semantics in `http` and `irc` modes
43
- hooks remain the pre-action fallback, tool summary path, and final-reply mirror path where the runtime does not expose a better broker-native reply stream
44
45
## What this gives you
46
47
For each local Gemini session launched through `gemini-relay`:
48
- a stable nick: `gemini-{repo}-{session}`
49
- immediate `online` post when the session starts
50
- real-time tool activity posts via hooks
51
- final assistant replies mirrored via `AfterAgent`
52
- continuous addressed IRC input injection into the live terminal session
53
- explicit pre-tool fallback interrupts before the next action
54
- `offline` post on exit
55
56
Transport choice:
57
- `SCUTTLEBOT_TRANSPORT=http` keeps the bridge/API path and now uses presence heartbeats
58
- `SCUTTLEBOT_TRANSPORT=irc` logs the session nick directly into Ergo for real presence
59
60
This is the production control path for a human-operated Gemini terminal. If you
61
want an always-on IRC-resident bot instead, use `cmd/gemini-agent`.
62
63
## One-machine install
64
65
Run from the repo checkout:
66
67
```bash
68
bash skills/gemini-relay/scripts/install-gemini-relay.sh \
69
--url http://localhost:8080 \
70
--token "$(./run.sh token)" \
71
--channel general
72
```
73
74
Then launch:
75
76
```bash
77
~/.local/bin/gemini-relay
78
```
79
80
## Fleet rollout
81
82
For multiple workstations or VM images:
83
84
1. Distribute this repo revision.
85
2. Run the tracked installer on each machine.
86
3. Launch Gemini through `~/.local/bin/gemini-relay` instead of `gemini`.
87
88
Example:
89
90
```bash
91
bash skills/gemini-relay/scripts/install-gemini-relay.sh \
92
--url http://scuttlebot.example.com:8080 \
93
--token "$SCUTTLEBOT_TOKEN" \
94
--channel fleet \
95
--transport irc \
96
--irc-addr scuttlebot.example.com:6667
97
```
98
99
If you need hooks present but inactive until the server is live:
100
101
```bash
102
bash skills/gemini-relay/scripts/install-gemini-relay.sh --disabled
103
```
104
105
Later, re-enable by editing `~/.config/scuttlebot-relay.env` or rerunning:
106
107
```bash
108
bash skills/gemini-relay/scripts/install-gemini-relay.sh --enabled
109
```
110
111
## What the installer changes
112
113
The installer is intentionally narrow. It:
114
- copies the tracked hook scripts into `~/.gemini/hooks/`
115
- builds and installs `gemini-relay` into `~/.local/bin/`
116
- merges required hook entries into `~/.gemini/settings.json`
117
- writes `SCUTTLEBOT_*` settings into `~/.config/scuttlebot-relay.env`
118
- defaults IRC auth to auto-registration by removing any stale `SCUTTLEBOT_IRC_PASS`
119
- keeps one backup copy as `*.bak` before overwriting an existing installed file
120
121
It does not:
122
- replace the real `gemini` binary in `PATH`
123
- force a fixed nick across sessions
124
- require IRC to be up at install time
125
126
Useful shared env knobs:
127
- `SCUTTLEBOT_TRANSPORT=http|irc` selects the connector backend
128
- `SCUTTLEBOT_CHANNEL` is the primary control channel
129
- `SCUTTLEBOT_CHANNELS=general,task-42` seeds extra startup work channels
130
- `SCUTTLEBOT_IRC_ADDR=127.0.0.1:6667` sets the real IRC address when transport is `irc`
131
- `SCUTTLEBOT_IRC_PASS=...` uses a fixed NickServ password instead of auto-registration; leave it unset for the default broker convention
132
- `SCUTTLEBOT_IRC_DELETE_ON_CLOSE=0` keeps auto-registered session nicks after clean exit
133
- `SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1` interrupts the live Gemini session when it appears busy
134
- `SCUTTLEBOT_POLL_INTERVAL=2s` controls how often the broker checks for new addressed IRC messages
135
- `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` controls HTTP presence touches; set `0` to disable
136
- `SCUTTLEBOT_AFTER_AGENT_MAX_POSTS=6` caps how many IRC messages one final Gemini reply may emit
137
- `SCUTTLEBOT_AFTER_AGENT_CHUNK_WIDTH=360` controls the maximum width of each mirrored reply chunk
138
139
Installer auth knobs:
140
- default or `--auto-register`: scrub `SCUTTLEBOT_IRC_PASS` from the shared env file and let the broker auto-register ephemeral session nicks
141
- `--irc-pass <passphrase>`: persist a fixed NickServ password in the shared env file
142
143
Live channel commands:
144
- `/channels`
145
- `/join #task-42`
146
- `/part #task-42`
147
148
## Operator workflow
149
150
1. Watch the configured channel in scuttlebot.
151
2. Wait for a new `gemini-{repo}-{session}` online post.
152
3. Mention that nick when you need to steer the session.
153
4. `cmd/gemini-relay` injects the addressed IRC message into the live terminal session.
154
5. The pre-tool hook still blocks on the next action if needed.
155
156
Examples:
157
158
```text
159
operator: gemini-scuttlebot-a1b2c3d4 stop and re-read bridge.go
160
operator: gemini-scuttlebot-a1b2c3d4 wrong file, inspect policies.go first
161
```
162
163
Ambient channel chat does not block the loop. Only explicit nick mentions do.
164
165
## When IRC/scuttlebot is down
166
167
Disable without uninstalling:
168
169
```bash
170
SCUTTLEBOT_HOOKS_ENABLED=0 ~/.local/bin/gemini-relay
171
```
172
173
Or persist the disabled state in the shared env file:
174
175
```bash
176
bash skills/gemini-relay/scripts/install-gemini-relay.sh --disabled
177
```
178
179
The hooks and broker soft-fail if the HTTP API is unavailable. Gemini still runs;
180
you just lose the IRC coordination layer until the server comes back.
181
182
## Adding more runtimes
183
184
Do not fork the protocol. Reuse the same control contract:
185
- post activity out after each action
186
- accept addressed operator instructions back in before the next action
187
- use stable, human-addressable session nicks
188
- keep the repo as the source of truth
189
190
The shared authoring contract lives in
191
[`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md).
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