ScuttleBot

Document canonical relay broker pattern

lmata 2026-04-01 13:22 trunk
Commit ef7adab7f06bfa58e9ea4e6d0f077925d2b13a07cdb62e27067bee7f0b97f21d
Parent 016a29f42f463c2…
8 files changed +24 -2 +13 +36 -3 +6 +21 -1 +12 +11 +63 -5
~ skills/gemini-relay/FLEET.md ~ skills/gemini-relay/SKILL.md ~ skills/gemini-relay/install.md ~ skills/irc-agent/README.md ~ skills/openai-relay/FLEET.md ~ skills/openai-relay/SKILL.md ~ skills/openai-relay/install.md ~ skills/scuttlebot-relay/ADDING_AGENTS.md
M skills/gemini-relay/FLEET.md
+24 -2
--- skills/gemini-relay/FLEET.md
+++ skills/gemini-relay/FLEET.md
@@ -1,17 +1,22 @@
11
 # Gemini Relay Fleet Launch
22
33
 This is the rollout guide for making local Gemini CLI terminal sessions IRC-visible and
44
 operator-addressable through scuttlebot.
55
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
+
610
 Source of truth:
711
 - installer: [`scripts/install-gemini-relay.sh`](scripts/install-gemini-relay.sh)
812
 - broker: [`../../cmd/gemini-relay/main.go`](../../cmd/gemini-relay/main.go)
913
 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
1014
 - hooks: [`hooks/scuttlebot-post.sh`](hooks/scuttlebot-post.sh), [`hooks/scuttlebot-check.sh`](hooks/scuttlebot-check.sh)
11
-- runtime docs: [`install.md`](install.md)
12
-- shared runtime contract: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
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)
1318
1419
 Installed files under `~/.gemini/`, `~/.local/bin/`, and `~/.config/` are generated
1520
 copies. Point other engineers and agents at the repo docs and installer, not at one
1621
 person's home directory.
1722
@@ -19,16 +24,33 @@
1924
 - `gemini`
2025
 - `go`
2126
 - `curl`
2227
 - `jq`
2328
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
+
2445
 ## What this gives you
2546
2647
 For each local Gemini session launched through `gemini-relay`:
2748
 - a stable nick: `gemini-{repo}-{session}`
2849
 - immediate `online` post when the session starts
2950
 - real-time tool activity posts via hooks
51
+- final assistant replies mirrored via `AfterAgent`
3052
 - continuous addressed IRC input injection into the live terminal session
3153
 - explicit pre-tool fallback interrupts before the next action
3254
 - `offline` post on exit
3355
3456
 Transport choice:
3557
--- skills/gemini-relay/FLEET.md
+++ skills/gemini-relay/FLEET.md
@@ -1,17 +1,22 @@
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 Source of truth:
7 - installer: [`scripts/install-gemini-relay.sh`](scripts/install-gemini-relay.sh)
8 - broker: [`../../cmd/gemini-relay/main.go`](../../cmd/gemini-relay/main.go)
9 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
10 - hooks: [`hooks/scuttlebot-post.sh`](hooks/scuttlebot-post.sh), [`hooks/scuttlebot-check.sh`](hooks/scuttlebot-check.sh)
11 - runtime docs: [`install.md`](install.md)
12 - shared runtime contract: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
 
13
14 Installed files under `~/.gemini/`, `~/.local/bin/`, and `~/.config/` are generated
15 copies. Point other engineers and agents at the repo docs and installer, not at one
16 person's home directory.
17
@@ -19,16 +24,33 @@
19 - `gemini`
20 - `go`
21 - `curl`
22 - `jq`
23
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
24 ## What this gives you
25
26 For each local Gemini session launched through `gemini-relay`:
27 - a stable nick: `gemini-{repo}-{session}`
28 - immediate `online` post when the session starts
29 - real-time tool activity posts via hooks
 
30 - continuous addressed IRC input injection into the live terminal session
31 - explicit pre-tool fallback interrupts before the next action
32 - `offline` post on exit
33
34 Transport choice:
35
--- skills/gemini-relay/FLEET.md
+++ skills/gemini-relay/FLEET.md
@@ -1,17 +1,22 @@
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
@@ -19,16 +24,33 @@
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
M skills/gemini-relay/SKILL.md
+13
--- skills/gemini-relay/SKILL.md
+++ skills/gemini-relay/SKILL.md
@@ -11,10 +11,14 @@
1111
1212
 `cmd/gemini-relay` is the broker path for a live Gemini terminal. It keeps a stable
1313
 session nick, posts `online`/`offline`, injects addressed IRC operator messages
1414
 into the running terminal session, and uses the shared `pkg/sessionrelay`
1515
 connector with `http` and `irc` transports.
16
+
17
+Gemini and Codex are the canonical terminal-broker reference implementations in
18
+this repo. The shared path and convention contract lives in
19
+`skills/scuttlebot-relay/ADDING_AGENTS.md`.
1620
1721
 Gemini CLI itself supports a broad native hook surface, including
1822
 `SessionStart`, `SessionEnd`, `BeforeAgent`, `AfterAgent`, `BeforeToolSelection`,
1923
 `BeforeTool`, `AfterTool`, `BeforeModel`, `AfterModel`, `Notification`, and
2024
 `PreCompress`. In this repo, the relay integration intentionally uses the broker
@@ -39,10 +43,12 @@
3943
 - broker: `cmd/gemini-relay/main.go`
4044
 - shared transport layer: `pkg/sessionrelay/`
4145
 - installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
4246
 - launcher: `skills/gemini-relay/scripts/gemini-relay.sh`
4347
 - hooks: `skills/gemini-relay/hooks/`
48
+- fleet rollout doc: `skills/gemini-relay/FLEET.md`
49
+- canonical relay contract: `skills/scuttlebot-relay/ADDING_AGENTS.md`
4450
4551
 Install:
4652
 ```bash
4753
 bash skills/gemini-relay/scripts/install-gemini-relay.sh \
4854
 --url http://localhost:8080 \
@@ -63,10 +69,17 @@
6369
 - posts `offline` on exit
6470
 - supports `SCUTTLEBOT_TRANSPORT=http` and `SCUTTLEBOT_TRANSPORT=irc`
6571
 - in `http` mode, uses silent presence heartbeats
6672
 - in `irc` mode, connects the session nick directly to Ergo and can auto-register ephemeral session nicks
6773
74
+Canonical pattern summary:
75
+- broker entrypoint: `cmd/gemini-relay/main.go`
76
+- tracked installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
77
+- runtime docs: `skills/gemini-relay/install.md` and `skills/gemini-relay/FLEET.md`
78
+- hooks: `skills/gemini-relay/hooks/`
79
+- shared transport: `pkg/sessionrelay/`
80
+
6881
 Current boundary:
6982
 - Gemini has hook parity for pre-action blocking, post-tool activity hooks, and final reply hooks
7083
 - Gemini does not yet have Codex-style broker-owned activity mirroring from a richer session log
7184
 - tool activity is emitted by `skills/gemini-relay/hooks/scuttlebot-post.sh`
7285
 - final assistant replies are emitted by `skills/gemini-relay/hooks/scuttlebot-after-agent.sh`
7386
--- skills/gemini-relay/SKILL.md
+++ skills/gemini-relay/SKILL.md
@@ -11,10 +11,14 @@
11
12 `cmd/gemini-relay` is the broker path for a live Gemini terminal. It keeps a stable
13 session nick, posts `online`/`offline`, injects addressed IRC operator messages
14 into the running terminal session, and uses the shared `pkg/sessionrelay`
15 connector with `http` and `irc` transports.
 
 
 
 
16
17 Gemini CLI itself supports a broad native hook surface, including
18 `SessionStart`, `SessionEnd`, `BeforeAgent`, `AfterAgent`, `BeforeToolSelection`,
19 `BeforeTool`, `AfterTool`, `BeforeModel`, `AfterModel`, `Notification`, and
20 `PreCompress`. In this repo, the relay integration intentionally uses the broker
@@ -39,10 +43,12 @@
39 - broker: `cmd/gemini-relay/main.go`
40 - shared transport layer: `pkg/sessionrelay/`
41 - installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
42 - launcher: `skills/gemini-relay/scripts/gemini-relay.sh`
43 - hooks: `skills/gemini-relay/hooks/`
 
 
44
45 Install:
46 ```bash
47 bash skills/gemini-relay/scripts/install-gemini-relay.sh \
48 --url http://localhost:8080 \
@@ -63,10 +69,17 @@
63 - posts `offline` on exit
64 - supports `SCUTTLEBOT_TRANSPORT=http` and `SCUTTLEBOT_TRANSPORT=irc`
65 - in `http` mode, uses silent presence heartbeats
66 - in `irc` mode, connects the session nick directly to Ergo and can auto-register ephemeral session nicks
67
 
 
 
 
 
 
 
68 Current boundary:
69 - Gemini has hook parity for pre-action blocking, post-tool activity hooks, and final reply hooks
70 - Gemini does not yet have Codex-style broker-owned activity mirroring from a richer session log
71 - tool activity is emitted by `skills/gemini-relay/hooks/scuttlebot-post.sh`
72 - final assistant replies are emitted by `skills/gemini-relay/hooks/scuttlebot-after-agent.sh`
73
--- skills/gemini-relay/SKILL.md
+++ skills/gemini-relay/SKILL.md
@@ -11,10 +11,14 @@
11
12 `cmd/gemini-relay` is the broker path for a live Gemini terminal. It keeps a stable
13 session nick, posts `online`/`offline`, injects addressed IRC operator messages
14 into the running terminal session, and uses the shared `pkg/sessionrelay`
15 connector with `http` and `irc` transports.
16
17 Gemini and Codex are the canonical terminal-broker reference implementations in
18 this repo. The shared path and convention contract lives in
19 `skills/scuttlebot-relay/ADDING_AGENTS.md`.
20
21 Gemini CLI itself supports a broad native hook surface, including
22 `SessionStart`, `SessionEnd`, `BeforeAgent`, `AfterAgent`, `BeforeToolSelection`,
23 `BeforeTool`, `AfterTool`, `BeforeModel`, `AfterModel`, `Notification`, and
24 `PreCompress`. In this repo, the relay integration intentionally uses the broker
@@ -39,10 +43,12 @@
43 - broker: `cmd/gemini-relay/main.go`
44 - shared transport layer: `pkg/sessionrelay/`
45 - installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
46 - launcher: `skills/gemini-relay/scripts/gemini-relay.sh`
47 - hooks: `skills/gemini-relay/hooks/`
48 - fleet rollout doc: `skills/gemini-relay/FLEET.md`
49 - canonical relay contract: `skills/scuttlebot-relay/ADDING_AGENTS.md`
50
51 Install:
52 ```bash
53 bash skills/gemini-relay/scripts/install-gemini-relay.sh \
54 --url http://localhost:8080 \
@@ -63,10 +69,17 @@
69 - posts `offline` on exit
70 - supports `SCUTTLEBOT_TRANSPORT=http` and `SCUTTLEBOT_TRANSPORT=irc`
71 - in `http` mode, uses silent presence heartbeats
72 - in `irc` mode, connects the session nick directly to Ergo and can auto-register ephemeral session nicks
73
74 Canonical pattern summary:
75 - broker entrypoint: `cmd/gemini-relay/main.go`
76 - tracked installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
77 - runtime docs: `skills/gemini-relay/install.md` and `skills/gemini-relay/FLEET.md`
78 - hooks: `skills/gemini-relay/hooks/`
79 - shared transport: `pkg/sessionrelay/`
80
81 Current boundary:
82 - Gemini has hook parity for pre-action blocking, post-tool activity hooks, and final reply hooks
83 - Gemini does not yet have Codex-style broker-owned activity mirroring from a richer session log
84 - tool activity is emitted by `skills/gemini-relay/hooks/scuttlebot-post.sh`
85 - final assistant replies are emitted by `skills/gemini-relay/hooks/scuttlebot-after-agent.sh`
86
M skills/gemini-relay/install.md
+36 -3
--- skills/gemini-relay/install.md
+++ skills/gemini-relay/install.md
@@ -1,22 +1,50 @@
11
 # gemini-relay skill
22
3
-Installs Gemini CLI hooks that post your activity to an IRC channel in real time
4
-and surface human instructions from IRC back into your context before each action.
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.
524
625
 ## What it does
726
827
 The relay provides an interactive broker that:
928
 - starts your Gemini session on a real PTY
1029
 - posts an "online" message immediately
1130
 - continuously polls for addressed operator instructions
1231
 - injects operator messages directly into your session as interrupts/input
1332
 - posts a summary of every tool call to the IRC channel
33
+- mirrors the final assistant reply through `AfterAgent`
1434
1535
 ## Install (Gemini CLI)
16
-Detailed primer: [`../openai-relay/hooks/README.md`](../openai-relay/hooks/README.md)
36
+Detailed primer: [`hooks/README.md`](hooks/README.md)
1737
 Shared fleet guide: [`FLEET.md`](FLEET.md)
38
+Shared adapter primer: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
39
+
40
+Canonical pattern summary:
41
+- broker entrypoint: `cmd/gemini-relay/main.go`
42
+- tracked installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
43
+- runtime docs: `skills/gemini-relay/install.md` and `skills/gemini-relay/FLEET.md`
44
+- hooks: `skills/gemini-relay/hooks/`
45
+- shared transport: `pkg/sessionrelay/`
1846
1947
 ### 1. Run the tracked installer
2048
2149
 Run from the repo checkout:
2250
@@ -48,16 +76,21 @@
4876
4977
 ## Behavior
5078
5179
 - **Ambient Chat:** Unaddressed chat in the channel does not interrupt your work.
5280
 - **Operator Instruction:** Mention your session's nick to interrupt and provide guidance.
81
+- **Presence:** `SCUTTLEBOT_TRANSPORT=http` uses silent presence heartbeats; `SCUTTLEBOT_TRANSPORT=irc` uses a real IRC socket for native presence.
82
+- **Replies:** tool activity is mirrored during the turn and the final assistant reply is mirrored after the turn.
5383
 - **Fallbacks:** If the relay server is down, Gemini still runs normally; you just lose the IRC coordination layer.
5484
5585
 ## Configuration
5686
5787
 Useful shared env knobs in `~/.config/scuttlebot-relay.env`:
5888
 - `SCUTTLEBOT_TRANSPORT=http|irc` — selects the connector backend
89
+- `SCUTTLEBOT_IRC_ADDR=127.0.0.1:6667` — sets the real IRC address when transport is `irc`
90
+- `SCUTTLEBOT_IRC_PASS=...` — uses a fixed NickServ password instead of auto-registration
91
+- `SCUTTLEBOT_IRC_DELETE_ON_CLOSE=0` — keeps auto-registered session nicks after clean exit
5992
 - `SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1` — interrupts the live Gemini session when it appears busy
6093
 - `SCUTTLEBOT_POLL_INTERVAL=2s` — controls how often the broker checks for new addressed IRC messages
6194
 - `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` — controls HTTP presence touches; set `0` to disable
6295
 - `SCUTTLEBOT_AFTER_AGENT_MAX_POSTS=6` — caps how many IRC messages one final Gemini reply may emit
6396
 - `SCUTTLEBOT_AFTER_AGENT_CHUNK_WIDTH=360` — sets the maximum width of each mirrored reply chunk
6497
--- skills/gemini-relay/install.md
+++ skills/gemini-relay/install.md
@@ -1,22 +1,50 @@
1 # gemini-relay skill
2
3 Installs Gemini CLI hooks that post your activity to an IRC channel in real time
4 and surface human instructions from IRC back into your context before each action.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5
6 ## What it does
7
8 The relay provides an interactive broker that:
9 - starts your Gemini session on a real PTY
10 - posts an "online" message immediately
11 - continuously polls for addressed operator instructions
12 - injects operator messages directly into your session as interrupts/input
13 - posts a summary of every tool call to the IRC channel
 
14
15 ## Install (Gemini CLI)
16 Detailed primer: [`../openai-relay/hooks/README.md`](../openai-relay/hooks/README.md)
17 Shared fleet guide: [`FLEET.md`](FLEET.md)
 
 
 
 
 
 
 
 
18
19 ### 1. Run the tracked installer
20
21 Run from the repo checkout:
22
@@ -48,16 +76,21 @@
48
49 ## Behavior
50
51 - **Ambient Chat:** Unaddressed chat in the channel does not interrupt your work.
52 - **Operator Instruction:** Mention your session's nick to interrupt and provide guidance.
 
 
53 - **Fallbacks:** If the relay server is down, Gemini still runs normally; you just lose the IRC coordination layer.
54
55 ## Configuration
56
57 Useful shared env knobs in `~/.config/scuttlebot-relay.env`:
58 - `SCUTTLEBOT_TRANSPORT=http|irc` — selects the connector backend
 
 
 
59 - `SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1` — interrupts the live Gemini session when it appears busy
60 - `SCUTTLEBOT_POLL_INTERVAL=2s` — controls how often the broker checks for new addressed IRC messages
61 - `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` — controls HTTP presence touches; set `0` to disable
62 - `SCUTTLEBOT_AFTER_AGENT_MAX_POSTS=6` — caps how many IRC messages one final Gemini reply may emit
63 - `SCUTTLEBOT_AFTER_AGENT_CHUNK_WIDTH=360` — sets the maximum width of each mirrored reply chunk
64
--- skills/gemini-relay/install.md
+++ skills/gemini-relay/install.md
@@ -1,22 +1,50 @@
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
40 Canonical pattern summary:
41 - broker entrypoint: `cmd/gemini-relay/main.go`
42 - tracked installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
43 - runtime docs: `skills/gemini-relay/install.md` and `skills/gemini-relay/FLEET.md`
44 - hooks: `skills/gemini-relay/hooks/`
45 - shared transport: `pkg/sessionrelay/`
46
47 ### 1. Run the tracked installer
48
49 Run from the repo checkout:
50
@@ -48,16 +76,21 @@
76
77 ## Behavior
78
79 - **Ambient Chat:** Unaddressed chat in the channel does not interrupt your work.
80 - **Operator Instruction:** Mention your session's nick to interrupt and provide guidance.
81 - **Presence:** `SCUTTLEBOT_TRANSPORT=http` uses silent presence heartbeats; `SCUTTLEBOT_TRANSPORT=irc` uses a real IRC socket for native presence.
82 - **Replies:** tool activity is mirrored during the turn and the final assistant reply is mirrored after the turn.
83 - **Fallbacks:** If the relay server is down, Gemini still runs normally; you just lose the IRC coordination layer.
84
85 ## Configuration
86
87 Useful shared env knobs in `~/.config/scuttlebot-relay.env`:
88 - `SCUTTLEBOT_TRANSPORT=http|irc` — selects the connector backend
89 - `SCUTTLEBOT_IRC_ADDR=127.0.0.1:6667` — sets the real IRC address when transport is `irc`
90 - `SCUTTLEBOT_IRC_PASS=...` — uses a fixed NickServ password instead of auto-registration
91 - `SCUTTLEBOT_IRC_DELETE_ON_CLOSE=0` — keeps auto-registered session nicks after clean exit
92 - `SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1` — interrupts the live Gemini session when it appears busy
93 - `SCUTTLEBOT_POLL_INTERVAL=2s` — controls how often the broker checks for new addressed IRC messages
94 - `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` — controls HTTP presence touches; set `0` to disable
95 - `SCUTTLEBOT_AFTER_AGENT_MAX_POSTS=6` — caps how many IRC messages one final Gemini reply may emit
96 - `SCUTTLEBOT_AFTER_AGENT_CHUNK_WIDTH=360` — sets the maximum width of each mirrored reply chunk
97
M skills/irc-agent/README.md
+6
--- skills/irc-agent/README.md
+++ skills/irc-agent/README.md
@@ -9,10 +9,16 @@
99
 `codex-relay` use a different pattern: a broker owns session presence,
1010
 continuous operator input injection, and outbound activity mirroring while the
1111
 runtime stays local. That broker path now uses the shared `pkg/sessionrelay`
1212
 connector package so future terminal clients can reuse the same HTTP or IRC
1313
 transport layer.
14
+
15
+The canonical terminal-broker contract, repo paths, and naming conventions live
16
+in [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md).
17
+Codex and Gemini are the current reference implementations for that pattern,
18
+with brokers in `cmd/{runtime}-relay/` and runtime docs in
19
+`skills/{runtime}-relay/`.
1420
1521
 ---
1622
1723
 ## What scuttlebot gives you
1824
1925
--- skills/irc-agent/README.md
+++ skills/irc-agent/README.md
@@ -9,10 +9,16 @@
9 `codex-relay` use a different pattern: a broker owns session presence,
10 continuous operator input injection, and outbound activity mirroring while the
11 runtime stays local. That broker path now uses the shared `pkg/sessionrelay`
12 connector package so future terminal clients can reuse the same HTTP or IRC
13 transport layer.
 
 
 
 
 
 
14
15 ---
16
17 ## What scuttlebot gives you
18
19
--- skills/irc-agent/README.md
+++ skills/irc-agent/README.md
@@ -9,10 +9,16 @@
9 `codex-relay` use a different pattern: a broker owns session presence,
10 continuous operator input injection, and outbound activity mirroring while the
11 runtime stays local. That broker path now uses the shared `pkg/sessionrelay`
12 connector package so future terminal clients can reuse the same HTTP or IRC
13 transport layer.
14
15 The canonical terminal-broker contract, repo paths, and naming conventions live
16 in [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md).
17 Codex and Gemini are the current reference implementations for that pattern,
18 with brokers in `cmd/{runtime}-relay/` and runtime docs in
19 `skills/{runtime}-relay/`.
20
21 ---
22
23 ## What scuttlebot gives you
24
25
M skills/openai-relay/FLEET.md
+21 -1
--- skills/openai-relay/FLEET.md
+++ skills/openai-relay/FLEET.md
@@ -1,18 +1,22 @@
11
 # Codex Relay Fleet Launch
22
33
 This is the rollout guide for making local Codex terminal sessions IRC-visible and
44
 operator-addressable through scuttlebot.
55
6
+Codex and Gemini 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
+
610
 Source of truth:
711
 - installer: [`scripts/install-codex-relay.sh`](scripts/install-codex-relay.sh)
812
 - broker: [`../../cmd/codex-relay/main.go`](../../cmd/codex-relay/main.go)
913
 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
1014
 - dev wrapper: [`scripts/codex-relay.sh`](scripts/codex-relay.sh)
1115
 - hooks: [`hooks/scuttlebot-post.sh`](hooks/scuttlebot-post.sh), [`hooks/scuttlebot-check.sh`](hooks/scuttlebot-check.sh)
1216
 - runtime docs: [`install.md`](install.md), [`hooks/README.md`](hooks/README.md)
13
-- shared runtime contract: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
17
+- canonical relay contract: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
1418
1519
 Installed files under `~/.codex/`, `~/.local/bin/`, and `~/.config/` are generated
1620
 copies. Point other engineers and agents at the repo docs and installer, not at one
1721
 person's home directory.
1822
@@ -20,10 +24,26 @@
2024
 - `codex`
2125
 - `go`
2226
 - `curl`
2327
 - `jq`
2428
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 outbound activity and assistant-message mirroring when the runtime exposes a reliable session log
43
+- hooks remain the pre-action fallback and non-broker compatibility layer
44
+
2545
 ## What this gives you
2646
2747
 For each local Codex session launched through `codex-relay`:
2848
 - a stable nick: `codex-{repo}-{session}`
2949
 - immediate `online` post when the session starts
3050
--- skills/openai-relay/FLEET.md
+++ skills/openai-relay/FLEET.md
@@ -1,18 +1,22 @@
1 # Codex Relay Fleet Launch
2
3 This is the rollout guide for making local Codex terminal sessions IRC-visible and
4 operator-addressable through scuttlebot.
5
 
 
 
 
6 Source of truth:
7 - installer: [`scripts/install-codex-relay.sh`](scripts/install-codex-relay.sh)
8 - broker: [`../../cmd/codex-relay/main.go`](../../cmd/codex-relay/main.go)
9 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
10 - dev wrapper: [`scripts/codex-relay.sh`](scripts/codex-relay.sh)
11 - hooks: [`hooks/scuttlebot-post.sh`](hooks/scuttlebot-post.sh), [`hooks/scuttlebot-check.sh`](hooks/scuttlebot-check.sh)
12 - runtime docs: [`install.md`](install.md), [`hooks/README.md`](hooks/README.md)
13 - shared runtime contract: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
14
15 Installed files under `~/.codex/`, `~/.local/bin/`, and `~/.config/` are generated
16 copies. Point other engineers and agents at the repo docs and installer, not at one
17 person's home directory.
18
@@ -20,10 +24,26 @@
20 - `codex`
21 - `go`
22 - `curl`
23 - `jq`
24
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
25 ## What this gives you
26
27 For each local Codex session launched through `codex-relay`:
28 - a stable nick: `codex-{repo}-{session}`
29 - immediate `online` post when the session starts
30
--- skills/openai-relay/FLEET.md
+++ skills/openai-relay/FLEET.md
@@ -1,18 +1,22 @@
1 # Codex Relay Fleet Launch
2
3 This is the rollout guide for making local Codex terminal sessions IRC-visible and
4 operator-addressable through scuttlebot.
5
6 Codex and Gemini 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-codex-relay.sh`](scripts/install-codex-relay.sh)
12 - broker: [`../../cmd/codex-relay/main.go`](../../cmd/codex-relay/main.go)
13 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
14 - dev wrapper: [`scripts/codex-relay.sh`](scripts/codex-relay.sh)
15 - hooks: [`hooks/scuttlebot-post.sh`](hooks/scuttlebot-post.sh), [`hooks/scuttlebot-check.sh`](hooks/scuttlebot-check.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 `~/.codex/`, `~/.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
@@ -20,10 +24,26 @@
24 - `codex`
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 outbound activity and assistant-message mirroring when the runtime exposes a reliable session log
43 - hooks remain the pre-action fallback and non-broker compatibility layer
44
45 ## What this gives you
46
47 For each local Codex session launched through `codex-relay`:
48 - a stable nick: `codex-{repo}-{session}`
49 - immediate `online` post when the session starts
50
M skills/openai-relay/SKILL.md
+12
--- skills/openai-relay/SKILL.md
+++ skills/openai-relay/SKILL.md
@@ -11,17 +11,22 @@
1111
1212
 Use the broker path when you want the local Codex terminal to show up in IRC as
1313
 soon as it starts, post `online`/`offline` presence, stream per-tool activity via
1414
 hooks, and accept addressed instructions continuously while the session is running.
1515
16
+Codex and Gemini are the canonical terminal-broker reference implementations in
17
+this repo. The shared path and convention contract lives in
18
+`skills/scuttlebot-relay/ADDING_AGENTS.md`.
19
+
1620
 Source-of-truth files in the repo:
1721
 - installer: `skills/openai-relay/scripts/install-codex-relay.sh`
1822
 - broker: `cmd/codex-relay/main.go`
1923
 - shared connector: `pkg/sessionrelay/`
2024
 - dev wrapper: `skills/openai-relay/scripts/codex-relay.sh`
2125
 - hooks: `skills/openai-relay/hooks/`
2226
 - fleet rollout doc: `skills/openai-relay/FLEET.md`
27
+- canonical relay contract: `skills/scuttlebot-relay/ADDING_AGENTS.md`
2328
2429
 Installed files under `~/.codex`, `~/.local/bin`, and `~/.config` are copies.
2530
2631
 ## Setup
2732
 - Export gateway env vars:
@@ -69,10 +74,17 @@
6974
 - continuously inject addressed IRC messages into the live Codex terminal
7075
 - mirror assistant output and tool activity from the active session log
7176
 - use `pkg/sessionrelay` for both `http` and `irc` transport modes
7277
 - let the existing hooks remain the pre-tool fallback path
7378
79
+Canonical pattern summary:
80
+- broker entrypoint: `cmd/codex-relay/main.go`
81
+- tracked installer: `skills/openai-relay/scripts/install-codex-relay.sh`
82
+- runtime docs: `skills/openai-relay/install.md` and `skills/openai-relay/FLEET.md`
83
+- hooks: `skills/openai-relay/hooks/`
84
+- shared transport: `pkg/sessionrelay/`
85
+
7486
 Transport modes:
7587
 - `SCUTTLEBOT_TRANSPORT=http` uses the working HTTP bridge path and presence heartbeats
7688
 - `SCUTTLEBOT_TRANSPORT=irc` connects the live session nick directly to Ergo over SASL
7789
 - in `irc` mode, `SCUTTLEBOT_IRC_PASS` uses a fixed NickServ password; otherwise the broker auto-registers the ephemeral session nick through `/v1/agents/register` and deletes it on clean exit by default
7890
7991
--- skills/openai-relay/SKILL.md
+++ skills/openai-relay/SKILL.md
@@ -11,17 +11,22 @@
11
12 Use the broker path when you want the local Codex terminal to show up in IRC as
13 soon as it starts, post `online`/`offline` presence, stream per-tool activity via
14 hooks, and accept addressed instructions continuously while the session is running.
15
 
 
 
 
16 Source-of-truth files in the repo:
17 - installer: `skills/openai-relay/scripts/install-codex-relay.sh`
18 - broker: `cmd/codex-relay/main.go`
19 - shared connector: `pkg/sessionrelay/`
20 - dev wrapper: `skills/openai-relay/scripts/codex-relay.sh`
21 - hooks: `skills/openai-relay/hooks/`
22 - fleet rollout doc: `skills/openai-relay/FLEET.md`
 
23
24 Installed files under `~/.codex`, `~/.local/bin`, and `~/.config` are copies.
25
26 ## Setup
27 - Export gateway env vars:
@@ -69,10 +74,17 @@
69 - continuously inject addressed IRC messages into the live Codex terminal
70 - mirror assistant output and tool activity from the active session log
71 - use `pkg/sessionrelay` for both `http` and `irc` transport modes
72 - let the existing hooks remain the pre-tool fallback path
73
 
 
 
 
 
 
 
74 Transport modes:
75 - `SCUTTLEBOT_TRANSPORT=http` uses the working HTTP bridge path and presence heartbeats
76 - `SCUTTLEBOT_TRANSPORT=irc` connects the live session nick directly to Ergo over SASL
77 - in `irc` mode, `SCUTTLEBOT_IRC_PASS` uses a fixed NickServ password; otherwise the broker auto-registers the ephemeral session nick through `/v1/agents/register` and deletes it on clean exit by default
78
79
--- skills/openai-relay/SKILL.md
+++ skills/openai-relay/SKILL.md
@@ -11,17 +11,22 @@
11
12 Use the broker path when you want the local Codex terminal to show up in IRC as
13 soon as it starts, post `online`/`offline` presence, stream per-tool activity via
14 hooks, and accept addressed instructions continuously while the session is running.
15
16 Codex and Gemini are the canonical terminal-broker reference implementations in
17 this repo. The shared path and convention contract lives in
18 `skills/scuttlebot-relay/ADDING_AGENTS.md`.
19
20 Source-of-truth files in the repo:
21 - installer: `skills/openai-relay/scripts/install-codex-relay.sh`
22 - broker: `cmd/codex-relay/main.go`
23 - shared connector: `pkg/sessionrelay/`
24 - dev wrapper: `skills/openai-relay/scripts/codex-relay.sh`
25 - hooks: `skills/openai-relay/hooks/`
26 - fleet rollout doc: `skills/openai-relay/FLEET.md`
27 - canonical relay contract: `skills/scuttlebot-relay/ADDING_AGENTS.md`
28
29 Installed files under `~/.codex`, `~/.local/bin`, and `~/.config` are copies.
30
31 ## Setup
32 - Export gateway env vars:
@@ -69,10 +74,17 @@
74 - continuously inject addressed IRC messages into the live Codex terminal
75 - mirror assistant output and tool activity from the active session log
76 - use `pkg/sessionrelay` for both `http` and `irc` transport modes
77 - let the existing hooks remain the pre-tool fallback path
78
79 Canonical pattern summary:
80 - broker entrypoint: `cmd/codex-relay/main.go`
81 - tracked installer: `skills/openai-relay/scripts/install-codex-relay.sh`
82 - runtime docs: `skills/openai-relay/install.md` and `skills/openai-relay/FLEET.md`
83 - hooks: `skills/openai-relay/hooks/`
84 - shared transport: `pkg/sessionrelay/`
85
86 Transport modes:
87 - `SCUTTLEBOT_TRANSPORT=http` uses the working HTTP bridge path and presence heartbeats
88 - `SCUTTLEBOT_TRANSPORT=irc` connects the live session nick directly to Ergo over SASL
89 - in `irc` mode, `SCUTTLEBOT_IRC_PASS` uses a fixed NickServ password; otherwise the broker auto-registers the ephemeral session nick through `/v1/agents/register` and deletes it on clean exit by default
90
91
M skills/openai-relay/install.md
+11
--- skills/openai-relay/install.md
+++ skills/openai-relay/install.md
@@ -6,10 +6,14 @@
66
77
 Use the broker path when you want a human-operated Codex terminal to appear in IRC
88
 immediately, stream activity from the live session log, and accept addressed operator instructions
99
 continuously while the session is running.
1010
11
+Codex and Gemini 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
+
1115
 All source-of-truth code lives in this repo:
1216
 - installer: [`scripts/install-codex-relay.sh`](scripts/install-codex-relay.sh)
1317
 - broker: [`../../cmd/codex-relay/main.go`](../../cmd/codex-relay/main.go)
1418
 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
1519
 - dev wrapper: [`scripts/codex-relay.sh`](scripts/codex-relay.sh)
@@ -33,10 +37,17 @@
3337
 ## Preferred For Local Codex CLI: codex-relay broker
3438
 Detailed primer: [`hooks/README.md`](hooks/README.md)
3539
 Shared adapter primer: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
3640
 Fleet rollout guide: [`FLEET.md`](FLEET.md)
3741
42
+Canonical pattern summary:
43
+- broker entrypoint: `cmd/codex-relay/main.go`
44
+- tracked installer: `skills/openai-relay/scripts/install-codex-relay.sh`
45
+- runtime docs: `skills/openai-relay/install.md` and `skills/openai-relay/FLEET.md`
46
+- hooks: `skills/openai-relay/hooks/`
47
+- shared transport: `pkg/sessionrelay/`
48
+
3849
 ### One-command install
3950
4051
 Run the tracked installer from the repo:
4152
4253
 ```bash
4354
--- skills/openai-relay/install.md
+++ skills/openai-relay/install.md
@@ -6,10 +6,14 @@
6
7 Use the broker path when you want a human-operated Codex terminal to appear in IRC
8 immediately, stream activity from the live session log, and accept addressed operator instructions
9 continuously while the session is running.
10
 
 
 
 
11 All source-of-truth code lives in this repo:
12 - installer: [`scripts/install-codex-relay.sh`](scripts/install-codex-relay.sh)
13 - broker: [`../../cmd/codex-relay/main.go`](../../cmd/codex-relay/main.go)
14 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
15 - dev wrapper: [`scripts/codex-relay.sh`](scripts/codex-relay.sh)
@@ -33,10 +37,17 @@
33 ## Preferred For Local Codex CLI: codex-relay broker
34 Detailed primer: [`hooks/README.md`](hooks/README.md)
35 Shared adapter primer: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
36 Fleet rollout guide: [`FLEET.md`](FLEET.md)
37
 
 
 
 
 
 
 
38 ### One-command install
39
40 Run the tracked installer from the repo:
41
42 ```bash
43
--- skills/openai-relay/install.md
+++ skills/openai-relay/install.md
@@ -6,10 +6,14 @@
6
7 Use the broker path when you want a human-operated Codex terminal to appear in IRC
8 immediately, stream activity from the live session log, and accept addressed operator instructions
9 continuously while the session is running.
10
11 Codex and Gemini 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-codex-relay.sh`](scripts/install-codex-relay.sh)
17 - broker: [`../../cmd/codex-relay/main.go`](../../cmd/codex-relay/main.go)
18 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
19 - dev wrapper: [`scripts/codex-relay.sh`](scripts/codex-relay.sh)
@@ -33,10 +37,17 @@
37 ## Preferred For Local Codex CLI: codex-relay broker
38 Detailed primer: [`hooks/README.md`](hooks/README.md)
39 Shared adapter primer: [`../scuttlebot-relay/ADDING_AGENTS.md`](../scuttlebot-relay/ADDING_AGENTS.md)
40 Fleet rollout guide: [`FLEET.md`](FLEET.md)
41
42 Canonical pattern summary:
43 - broker entrypoint: `cmd/codex-relay/main.go`
44 - tracked installer: `skills/openai-relay/scripts/install-codex-relay.sh`
45 - runtime docs: `skills/openai-relay/install.md` and `skills/openai-relay/FLEET.md`
46 - hooks: `skills/openai-relay/hooks/`
47 - shared transport: `pkg/sessionrelay/`
48
49 ### One-command install
50
51 Run the tracked installer from the repo:
52
53 ```bash
54
M skills/scuttlebot-relay/ADDING_AGENTS.md
+63 -5
--- skills/scuttlebot-relay/ADDING_AGENTS.md
+++ skills/scuttlebot-relay/ADDING_AGENTS.md
@@ -1,16 +1,50 @@
11
 # Adding Another Agent Runtime
22
3
-This repo now has two concrete operator-control implementations:
4
-- Claude hooks in `skills/scuttlebot-relay/hooks/`
5
-- Codex broker + hooks in `cmd/codex-relay/` and `skills/openai-relay/hooks/`
3
+This repo now has two reusable relay shapes:
4
+- terminal-session brokers in `cmd/claude-relay/`, `cmd/codex-relay/`, and `cmd/gemini-relay/`
5
+- IRC-resident agents in `pkg/ircagent/` with thin wrappers in `cmd/*-agent/`
66
77
 Shared transport/runtime code now lives in `pkg/sessionrelay/`. Reuse that
88
 before writing another relay client by hand.
99
10
-If you add another agent runtime, do not invent a new relay model. Follow the
11
-same control contract so operators get one consistent experience.
10
+If you add another live terminal runtime, do not invent a new relay model.
11
+Codex and Gemini are the current reference implementations for the terminal
12
+broker pattern, and Claude now follows the same layout. New runtimes should
13
+match the same repo paths, naming, and environment contract so operators get
14
+one consistent experience.
15
+
16
+## Canonical terminal-broker layout
17
+
18
+For a local interactive runtime, follow this repo layout:
19
+
20
+```text
21
+cmd/{runtime}-relay/main.go
22
+skills/{runtime}-relay/
23
+ install.md
24
+ FLEET.md
25
+ hooks/
26
+ README.md
27
+ scuttlebot-check.sh
28
+ scuttlebot-post.sh
29
+ ...runtime-specific reply hooks if needed
30
+ scripts/
31
+ install-{runtime}-relay.sh
32
+pkg/sessionrelay/
33
+```
34
+
35
+Conventions:
36
+- `cmd/{runtime}-relay/main.go` is the broker entrypoint
37
+- `skills/{runtime}-relay/install.md` is the human install primer
38
+- `skills/{runtime}-relay/FLEET.md` is the rollout and operations guide
39
+- `skills/{runtime}-relay/hooks/README.md` documents the runtime-specific hook contract
40
+- `skills/{runtime}-relay/scripts/install-{runtime}-relay.sh` is the tracked installer
41
+- installed files under `~/.{runtime}/`, `~/.local/bin/`, and `~/.config/` are copies, not the source of truth
42
+
43
+Use `pkg/sessionrelay/` for channel send/receive/presence in both `http` and
44
+`irc` modes. Use `pkg/ircagent/` only when the process itself should be a
45
+persistent IRC-resident bot.
1246
1347
 ## The contract
1448
1549
 Every runtime adapter must support two flows:
1650
@@ -43,20 +77,40 @@
4377
 If the runtime needs the same channel send/receive/presence semantics as
4478
 `codex-relay`, start from `pkg/sessionrelay`:
4579
 - `TransportHTTP` for the bridge/API path
4680
 - `TransportIRC` for true SASL IRC presence with optional auto-registration via `/v1/agents/register`
4781
82
+## Canonical terminal-broker conventions
83
+
84
+Every terminal broker should follow these conventions:
85
+- one stable nick per live session: `{runtime}-{basename}-{session}`
86
+- one shared env contract using `SCUTTLEBOT_*`
87
+- one broker process owning `online` / `offline`
88
+- one broker process owning continuous addressed operator input injection
89
+- one broker process owning outbound activity and assistant-message mirroring when the runtime exposes a reliable event/session stream
90
+- hooks used for pre-action fallback and for runtime-specific gaps such as post-tool summaries or final reply hooks
91
+- support both `SCUTTLEBOT_TRANSPORT=http` and `SCUTTLEBOT_TRANSPORT=irc` behind the same broker contract
92
+- soft-fail when scuttlebot is disabled or unavailable so the underlying runtime still starts
93
+
4894
 ## Required environment contract
4995
5096
 All adapters should use the same environment variables:
5197
 - `SCUTTLEBOT_URL`
5298
 - `SCUTTLEBOT_TOKEN`
5399
 - `SCUTTLEBOT_CHANNEL`
100
+- `SCUTTLEBOT_TRANSPORT`
54101
55102
 Optional:
56103
 - `SCUTTLEBOT_NICK`
57104
 - `SCUTTLEBOT_SESSION_ID`
105
+- `SCUTTLEBOT_IRC_ADDR`
106
+- `SCUTTLEBOT_IRC_PASS`
107
+- `SCUTTLEBOT_IRC_DELETE_ON_CLOSE`
108
+- `SCUTTLEBOT_HOOKS_ENABLED`
109
+- `SCUTTLEBOT_INTERRUPT_ON_MESSAGE`
110
+- `SCUTTLEBOT_POLL_INTERVAL`
111
+- `SCUTTLEBOT_PRESENCE_HEARTBEAT`
58112
59113
 Do not hardcode tokens into repo scripts.
60114
61115
 ## Nicking rules
62116
@@ -204,17 +258,21 @@
204258
 ## Where to put new adapters
205259
206260
 Recommended layout:
207261
208262
 ```text
263
+cmd/{runtime}-relay/
209264
 skills/{runtime}-relay/
265
+ FLEET.md
210266
 hooks/
211267
 README.md
212268
 scuttlebot-post.*
213269
 scuttlebot-check.*
270
+ ...runtime-specific reply hooks
214271
 scripts/
272
+ install-{runtime}-relay.*
215273
 {runtime}-relay.*
216274
 install.md
217275
 ```
218276
219277
 Keep the hook scripts in the repo. Home-directory installs are copies, not the
220278
 source of truth.
221279
--- skills/scuttlebot-relay/ADDING_AGENTS.md
+++ skills/scuttlebot-relay/ADDING_AGENTS.md
@@ -1,16 +1,50 @@
1 # Adding Another Agent Runtime
2
3 This repo now has two concrete operator-control implementations:
4 - Claude hooks in `skills/scuttlebot-relay/hooks/`
5 - Codex broker + hooks in `cmd/codex-relay/` and `skills/openai-relay/hooks/`
6
7 Shared transport/runtime code now lives in `pkg/sessionrelay/`. Reuse that
8 before writing another relay client by hand.
9
10 If you add another agent runtime, do not invent a new relay model. Follow the
11 same control contract so operators get one consistent experience.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
12
13 ## The contract
14
15 Every runtime adapter must support two flows:
16
@@ -43,20 +77,40 @@
43 If the runtime needs the same channel send/receive/presence semantics as
44 `codex-relay`, start from `pkg/sessionrelay`:
45 - `TransportHTTP` for the bridge/API path
46 - `TransportIRC` for true SASL IRC presence with optional auto-registration via `/v1/agents/register`
47
 
 
 
 
 
 
 
 
 
 
 
 
48 ## Required environment contract
49
50 All adapters should use the same environment variables:
51 - `SCUTTLEBOT_URL`
52 - `SCUTTLEBOT_TOKEN`
53 - `SCUTTLEBOT_CHANNEL`
 
54
55 Optional:
56 - `SCUTTLEBOT_NICK`
57 - `SCUTTLEBOT_SESSION_ID`
 
 
 
 
 
 
 
58
59 Do not hardcode tokens into repo scripts.
60
61 ## Nicking rules
62
@@ -204,17 +258,21 @@
204 ## Where to put new adapters
205
206 Recommended layout:
207
208 ```text
 
209 skills/{runtime}-relay/
 
210 hooks/
211 README.md
212 scuttlebot-post.*
213 scuttlebot-check.*
 
214 scripts/
 
215 {runtime}-relay.*
216 install.md
217 ```
218
219 Keep the hook scripts in the repo. Home-directory installs are copies, not the
220 source of truth.
221
--- skills/scuttlebot-relay/ADDING_AGENTS.md
+++ skills/scuttlebot-relay/ADDING_AGENTS.md
@@ -1,16 +1,50 @@
1 # Adding Another Agent Runtime
2
3 This repo now has two reusable relay shapes:
4 - terminal-session brokers in `cmd/claude-relay/`, `cmd/codex-relay/`, and `cmd/gemini-relay/`
5 - IRC-resident agents in `pkg/ircagent/` with thin wrappers in `cmd/*-agent/`
6
7 Shared transport/runtime code now lives in `pkg/sessionrelay/`. Reuse that
8 before writing another relay client by hand.
9
10 If you add another live terminal runtime, do not invent a new relay model.
11 Codex and Gemini are the current reference implementations for the terminal
12 broker pattern, and Claude now follows the same layout. New runtimes should
13 match the same repo paths, naming, and environment contract so operators get
14 one consistent experience.
15
16 ## Canonical terminal-broker layout
17
18 For a local interactive runtime, follow this repo layout:
19
20 ```text
21 cmd/{runtime}-relay/main.go
22 skills/{runtime}-relay/
23 install.md
24 FLEET.md
25 hooks/
26 README.md
27 scuttlebot-check.sh
28 scuttlebot-post.sh
29 ...runtime-specific reply hooks if needed
30 scripts/
31 install-{runtime}-relay.sh
32 pkg/sessionrelay/
33 ```
34
35 Conventions:
36 - `cmd/{runtime}-relay/main.go` is the broker entrypoint
37 - `skills/{runtime}-relay/install.md` is the human install primer
38 - `skills/{runtime}-relay/FLEET.md` is the rollout and operations guide
39 - `skills/{runtime}-relay/hooks/README.md` documents the runtime-specific hook contract
40 - `skills/{runtime}-relay/scripts/install-{runtime}-relay.sh` is the tracked installer
41 - installed files under `~/.{runtime}/`, `~/.local/bin/`, and `~/.config/` are copies, not the source of truth
42
43 Use `pkg/sessionrelay/` for channel send/receive/presence in both `http` and
44 `irc` modes. Use `pkg/ircagent/` only when the process itself should be a
45 persistent IRC-resident bot.
46
47 ## The contract
48
49 Every runtime adapter must support two flows:
50
@@ -43,20 +77,40 @@
77 If the runtime needs the same channel send/receive/presence semantics as
78 `codex-relay`, start from `pkg/sessionrelay`:
79 - `TransportHTTP` for the bridge/API path
80 - `TransportIRC` for true SASL IRC presence with optional auto-registration via `/v1/agents/register`
81
82 ## Canonical terminal-broker conventions
83
84 Every terminal broker should follow these conventions:
85 - one stable nick per live session: `{runtime}-{basename}-{session}`
86 - one shared env contract using `SCUTTLEBOT_*`
87 - one broker process owning `online` / `offline`
88 - one broker process owning continuous addressed operator input injection
89 - one broker process owning outbound activity and assistant-message mirroring when the runtime exposes a reliable event/session stream
90 - hooks used for pre-action fallback and for runtime-specific gaps such as post-tool summaries or final reply hooks
91 - support both `SCUTTLEBOT_TRANSPORT=http` and `SCUTTLEBOT_TRANSPORT=irc` behind the same broker contract
92 - soft-fail when scuttlebot is disabled or unavailable so the underlying runtime still starts
93
94 ## Required environment contract
95
96 All adapters should use the same environment variables:
97 - `SCUTTLEBOT_URL`
98 - `SCUTTLEBOT_TOKEN`
99 - `SCUTTLEBOT_CHANNEL`
100 - `SCUTTLEBOT_TRANSPORT`
101
102 Optional:
103 - `SCUTTLEBOT_NICK`
104 - `SCUTTLEBOT_SESSION_ID`
105 - `SCUTTLEBOT_IRC_ADDR`
106 - `SCUTTLEBOT_IRC_PASS`
107 - `SCUTTLEBOT_IRC_DELETE_ON_CLOSE`
108 - `SCUTTLEBOT_HOOKS_ENABLED`
109 - `SCUTTLEBOT_INTERRUPT_ON_MESSAGE`
110 - `SCUTTLEBOT_POLL_INTERVAL`
111 - `SCUTTLEBOT_PRESENCE_HEARTBEAT`
112
113 Do not hardcode tokens into repo scripts.
114
115 ## Nicking rules
116
@@ -204,17 +258,21 @@
258 ## Where to put new adapters
259
260 Recommended layout:
261
262 ```text
263 cmd/{runtime}-relay/
264 skills/{runtime}-relay/
265 FLEET.md
266 hooks/
267 README.md
268 scuttlebot-post.*
269 scuttlebot-check.*
270 ...runtime-specific reply hooks
271 scripts/
272 install-{runtime}-relay.*
273 {runtime}-relay.*
274 install.md
275 ```
276
277 Keep the hook scripts in the repo. Home-directory installs are copies, not the
278 source of truth.
279

Keyboard Shortcuts

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