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