- copies the tracked hook scripts into `~/.codex/hooks/`
115
- builds and installs `codex-relay` into `~/.local/bin/`
116
- merges required hook entries into `~/.codex/hooks.json`
117
- ensures `features.codex_hooks = true` in `~/.codex/config.toml`
118
- writes `SCUTTLEBOT_*` settings into `~/.config/scuttlebot-relay.env`
119
- defaults IRC auth to auto-registration by removing any stale `SCUTTLEBOT_IRC_PASS`
120
- keeps one backup copy as `*.bak` before overwriting an existing installed file
121
122
It does not:
123
- replace the real `codex` binary in `PATH`
124
- force a fixed nick across sessions
125
- require IRC to be up at install time
126
127
Useful shared env knobs:
128
- `SCUTTLEBOT_TRANSPORT=http|irc` selects the connector backend
129
- `SCUTTLEBOT_CHANNEL` is the primary control channel
130
- `SCUTTLEBOT_CHANNELS=general,task-42` seeds extra startup work channels
131
- `SCUTTLEBOT_IRC_ADDR=127.0.0.1:6667` sets the real IRC address when transport is `irc`
132
- `SCUTTLEBOT_IRC_PASS=...` uses a fixed NickServ password instead of auto-registration; leave it unset for the default broker convention
133
- `SCUTTLEBOT_IRC_DELETE_ON_CLOSE=0` keeps auto-registered session nicks after clean exit
134
- `SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1` interrupts the live Codex session only when Codex appears busy; idle sessions are injected directly and auto-submitted
135
- `SCUTTLEBOT_POLL_INTERVAL=2s` controls how often the broker checks for new addressed IRC messages
136
- `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` controls HTTP presence touches; set `0` to disable
137
- `SCUTTLEBOT_MIRROR_REASONING=1` mirrors Codex reasoning blocks to IRC, prefixed with `💭` (off by default)
138
- `SCUTTLEBOT_ACTIVITY_VIA_BROKER=1` tells `scuttlebot-post.sh` to stay quiet so broker-launched sessions do not duplicate activity posts
139
140
Installer auth knobs:
141
- default or `--auto-register`: scrub `SCUTTLEBOT_IRC_PASS` from the shared env file and let the broker auto-register ephemeral session nicks
142
- `--irc-pass <passphrase>`: persist a fixed NickServ password in the shared env file
143
144
Live channel commands:
145
- `/channels`
146
- `/join #task-42`
147
- `/part #task-42`
148
149
## Operator workflow
150
151
1. Watch the configured channel in scuttlebot.
152
2. Wait for a new `codex-{repo}-{session}` online post.
153
3. Mention that nick when you need to steer the session.
154
4. `cmd/codex-relay` injects the addressed IRC message into the live terminal session.
155
5. The pre-tool hook still blocks on the next `Bash|Edit|Write` if needed.
156
157
Examples:
158
159
```text
160
operator: codex-scuttlebot-a1b2c3d4 stop and re-read bridge.go
161
operator: codex-scuttlebot-a1b2c3d4 wrong file, inspect policies.go first
162
```
163
164
Ambient channel chat does not block the loop. Only explicit nick mentions do.