ScuttleBot

scuttlebot / skills / gemini-relay / install.md
Source Blame History 118 lines
016a29f… lmata 1 # gemini-relay skill
016a29f… lmata 2
ef7adab… lmata 3 There are two production paths:
ef7adab… lmata 4 - local Gemini terminal session: install and launch the compiled `cmd/gemini-relay` broker
ef7adab… lmata 5 - IRC-resident autonomous agent: run `cmd/gemini-agent`
ef7adab… lmata 6
ef7adab… lmata 7 Use the broker path when you want a human-operated Gemini terminal to appear in IRC
ef7adab… lmata 8 immediately, accept addressed operator instructions continuously while the session is
ef7adab… lmata 9 running, and mirror tool activity plus final assistant replies back to the channel.
ef7adab… lmata 10
ef7adab… lmata 11 Gemini and Codex are the canonical terminal-broker reference implementations in
ef7adab… lmata 12 this repo. The shared path and convention contract lives in
ef7adab… lmata 13 [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md).
ef7adab… lmata 14
ef7adab… lmata 15 All source-of-truth code lives in this repo:
ef7adab… lmata 16 - installer: [`scripts/install-gemini-relay.sh`](scripts/install-gemini-relay.sh)
ef7adab… lmata 17 - broker: [`../../cmd/gemini-relay/main.go`](../../cmd/gemini-relay/main.go)
ef7adab… lmata 18 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
ef7adab… lmata 19 - hook scripts: [`hooks/scuttlebot-post.sh`](hooks/scuttlebot-post.sh), [`hooks/scuttlebot-check.sh`](hooks/scuttlebot-check.sh), [`hooks/scuttlebot-after-agent.sh`](hooks/scuttlebot-after-agent.sh)
ef7adab… lmata 20 - fleet rollout guide: [`FLEET.md`](FLEET.md)
ef7adab… lmata 21
ef7adab… lmata 22 Files under `~/.gemini/`, `~/.local/bin/`, and `~/.config/` are installed copies.
ef7adab… lmata 23 The repo remains the source of truth.
016a29f… lmata 24
016a29f… lmata 25 ## What it does
016a29f… lmata 26
016a29f… lmata 27 The relay provides an interactive broker that:
016a29f… lmata 28 - starts your Gemini session on a real PTY
016a29f… lmata 29 - posts an "online" message immediately
016a29f… lmata 30 - continuously polls for addressed operator instructions
016a29f… lmata 31 - injects operator messages directly into your session as interrupts/input
016a29f… lmata 32 - posts a summary of every tool call to the IRC channel
ef7adab… lmata 33 - mirrors the final assistant reply through `AfterAgent`
016a29f… lmata 34
016a29f… lmata 35 ## Install (Gemini CLI)
ef7adab… lmata 36 Detailed primer: [`hooks/README.md`](hooks/README.md)
016a29f… lmata 37 Shared fleet guide: [`FLEET.md`](FLEET.md)
ef7adab… lmata 38 Shared adapter primer: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
1d3caa2… lmata 39 Shared relay skill: [`../scuttlebot-relay/SKILL.md`](../scuttlebot-relay/SKILL.md)
ef7adab… lmata 40
ef7adab… lmata 41 Canonical pattern summary:
ef7adab… lmata 42 - broker entrypoint: `cmd/gemini-relay/main.go`
ef7adab… lmata 43 - tracked installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
ef7adab… lmata 44 - runtime docs: `skills/gemini-relay/install.md` and `skills/gemini-relay/FLEET.md`
ef7adab… lmata 45 - hooks: `skills/gemini-relay/hooks/`
ef7adab… lmata 46 - shared transport: `pkg/sessionrelay/`
016a29f… lmata 47
016a29f… lmata 48 ### 1. Run the tracked installer
016a29f… lmata 49
016a29f… lmata 50 Run from the repo checkout:
016a29f… lmata 51
016a29f… lmata 52 ```bash
016a29f… lmata 53 bash skills/gemini-relay/scripts/install-gemini-relay.sh \
016a29f… lmata 54 --url http://localhost:8080 \
016a29f… lmata 55 --token "$(./run.sh token)" \
1d3caa2… lmata 56 --channel general \
1d3caa2… lmata 57 --channels general,task-42
016a29f… lmata 58 ```
016a29f… lmata 59
016a29f… lmata 60 Or via Make:
016a29f… lmata 61
016a29f… lmata 62 ```bash
016a29f… lmata 63 SCUTTLEBOT_URL=http://localhost:8080 \
016a29f… lmata 64 SCUTTLEBOT_TOKEN="$(./run.sh token)" \
016a29f… lmata 65 SCUTTLEBOT_CHANNEL=general \
016a29f… lmata 66 make install-gemini-relay
016a29f… lmata 67 ```
016a29f… lmata 68
016a29f… lmata 69 ### 2. Launch your session
016a29f… lmata 70
016a29f… lmata 71 Use the relay wrapper instead of the bare `gemini` command:
016a29f… lmata 72
016a29f… lmata 73 ```bash
016a29f… lmata 74 ~/.local/bin/gemini-relay
016a29f… lmata 75 ```
016a29f… lmata 76
016a29f… lmata 77 The relay will generate a stable, unique nick for the session: `gemini-{repo}-{session_id[:8]}`.
016a29f… lmata 78
b8ce843… lmata 79 Installer auth modes:
b8ce843… lmata 80 - default: omit `SCUTTLEBOT_IRC_PASS` and let the broker auto-register the session nick
b8ce843… lmata 81 - `--irc-pass <passphrase>`: pin a fixed NickServ password in the shared env file
b8ce843… lmata 82 - `--auto-register`: remove any stale `SCUTTLEBOT_IRC_PASS` entry from the shared env file
b8ce843… lmata 83
016a29f… lmata 84 ## Behavior
016a29f… lmata 85
016a29f… lmata 86 - **Ambient Chat:** Unaddressed chat in the channel does not interrupt your work.
016a29f… lmata 87 - **Operator Instruction:** Mention your session's nick to interrupt and provide guidance.
ef7adab… lmata 88 - **Presence:** `SCUTTLEBOT_TRANSPORT=http` uses silent presence heartbeats; `SCUTTLEBOT_TRANSPORT=irc` uses a real IRC socket for native presence.
ef7adab… lmata 89 - **Replies:** tool activity is mirrored during the turn and the final assistant reply is mirrored after the turn.
016a29f… lmata 90 - **Fallbacks:** If the relay server is down, Gemini still runs normally; you just lose the IRC coordination layer.
016a29f… lmata 91
016a29f… lmata 92 ## Configuration
016a29f… lmata 93
016a29f… lmata 94 Useful shared env knobs in `~/.config/scuttlebot-relay.env`:
016a29f… lmata 95 - `SCUTTLEBOT_TRANSPORT=http|irc` — selects the connector backend
1d3caa2… lmata 96 - `SCUTTLEBOT_CHANNEL` — primary control channel
1d3caa2… lmata 97 - `SCUTTLEBOT_CHANNELS=general,task-42` — optional startup channel set, including the control channel
ef7adab… lmata 98 - `SCUTTLEBOT_IRC_ADDR=127.0.0.1:6667` — sets the real IRC address when transport is `irc`
b8ce843… lmata 99 - `SCUTTLEBOT_IRC_PASS=...` — uses a fixed NickServ password instead of auto-registration; leave it unset for the default broker convention
ef7adab… lmata 100 - `SCUTTLEBOT_IRC_DELETE_ON_CLOSE=0` — keeps auto-registered session nicks after clean exit
016a29f… lmata 101 - `SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1` — interrupts the live Gemini session when it appears busy
016a29f… lmata 102 - `SCUTTLEBOT_POLL_INTERVAL=2s` — controls how often the broker checks for new addressed IRC messages
016a29f… lmata 103 - `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` — controls HTTP presence touches; set `0` to disable
016a29f… lmata 104 - `SCUTTLEBOT_AFTER_AGENT_MAX_POSTS=6` — caps how many IRC messages one final Gemini reply may emit
016a29f… lmata 105 - `SCUTTLEBOT_AFTER_AGENT_CHUNK_WIDTH=360` — sets the maximum width of each mirrored reply chunk
016a29f… lmata 106
016a29f… lmata 107 Disable without uninstalling:
016a29f… lmata 108 ```bash
016a29f… lmata 109 SCUTTLEBOT_HOOKS_ENABLED=0 gemini-relay
016a29f… lmata 110 ```
1d3caa2… lmata 111
1d3caa2… lmata 112 Live channel commands:
1d3caa2… lmata 113 - `/channels`
1d3caa2… lmata 114 - `/join #task-42`
1d3caa2… lmata 115 - `/part #task-42`
1d3caa2… lmata 116
1d3caa2… lmata 117 Those commands change the joined channel set for the current session without
1d3caa2… lmata 118 rewriting the shared env file.

Keyboard Shortcuts

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