- 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
51
1. Activity out
52
- during live work, mirror meaningful tool/action activity back to scuttlebot
53
- if the runtime exposes assistant progress or reply text, mirror that too
54
- use a stable session nick
55
56
2. Instruction back in
57
- continuously or before the next action, fetch recent messages from scuttlebot
58
- filter to explicit operator instructions for this session
59
- surface the instruction back into the runtime using that runtime's native hook/block mechanism
60
61
If a runtime cannot surface a blocking instruction before the next action, it does
62
not yet have parity with the Claude/Codex hook path.
63
64
For runtimes that are live interactive terminal sessions, ship a small broker or
65
launcher wrapper that:
66
- exports a stable session id before the runtime starts
67
- derives and exports the session nick once
68
- posts `online` immediately on startup
69
- mirrors activity from the runtime's own event/session log or PTY stream
70
- posts `offline` on exit
71
- soft-fails if scuttlebot is disabled or unreachable
72
73
Hooks remain useful for pre-action fallback and for runtimes that do not have a
74
broker yet, but hook-only telemetry is not the production pattern for
75
interactive sessions.
76
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
- installer default is auto-registration: leave `SCUTTLEBOT_IRC_PASS` unset and remove stale fixed-pass values unless the operator explicitly requests a fixed identity
88
- one primary control channel plus optional joined work channels
89
- one broker process owning `online` / `offline`
90
- one broker process owning continuous addressed operator input injection
91
- one broker process owning outbound activity and assistant-message mirroring when the runtime exposes a reliable event/session stream
92
- hooks used for pre-action fallback and for runtime-specific gaps such as post-tool summaries or final reply hooks
93
- support both `SCUTTLEBOT_TRANSPORT=http` and `SCUTTLEBOT_TRANSPORT=irc` behind the same broker contract
94
- soft-fail when scuttlebot is disabled or unavailable so the underlying runtime still starts
95
96
## Required environment contract
97
98
All adapters should use the same environment variables:
99
- `SCUTTLEBOT_URL`
100
- `SCUTTLEBOT_TOKEN`
101
- `SCUTTLEBOT_CHANNEL`
102
- `SCUTTLEBOT_CHANNELS`
103
- `SCUTTLEBOT_TRANSPORT`
104
105
Optional:
106
- `SCUTTLEBOT_NICK`
107
- `SCUTTLEBOT_SESSION_ID`
108
- `SCUTTLEBOT_IRC_ADDR`
109
- `SCUTTLEBOT_IRC_PASS`
110
- `SCUTTLEBOT_IRC_DELETE_ON_CLOSE`
111
- `SCUTTLEBOT_HOOKS_ENABLED`
112
- `SCUTTLEBOT_INTERRUPT_ON_MESSAGE`
113
- `SCUTTLEBOT_POLL_INTERVAL`
114
- `SCUTTLEBOT_PRESENCE_HEARTBEAT`
115
- `SCUTTLEBOT_CHANNEL_STATE_FILE`
116
117
Do not hardcode tokens into repo scripts.
118
For terminal-session brokers, treat `SCUTTLEBOT_IRC_PASS` as an explicit
119
fixed-identity override, not a default.
120
121
Channel semantics:
122
- `SCUTTLEBOT_CHANNEL` is the primary control channel
123
- `SCUTTLEBOT_CHANNELS` is the startup channel set and should include the control channel
124
- runtime `/join`, `/part`, and `/channels` commands may change the live channel set for one session without rewriting the shared env file