ScuttleBot

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

Keyboard Shortcuts

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