|
1
|
# Claude Relay Fleet Launch |
|
2
|
|
|
3
|
This is the rollout guide for making local Claude Code terminal sessions IRC-visible and |
|
4
|
operator-addressable through scuttlebot. |
|
5
|
|
|
6
|
Source of truth: |
|
7
|
- installer: [`scripts/install-claude-relay.sh`](scripts/install-claude-relay.sh) |
|
8
|
- broker: [`../../cmd/claude-relay/main.go`](../../cmd/claude-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: [`ADDING_AGENTS.md`](ADDING_AGENTS.md) |
|
13
|
|
|
14
|
Installed files under `~/.claude/`, `~/.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
|
|
|
18
|
Runtime prerequisites: |
|
19
|
- `claude` (Claude Code) |
|
20
|
- `go` |
|
21
|
- `curl` |
|
22
|
- `jq` |
|
23
|
|
|
24
|
## What this gives you |
|
25
|
|
|
26
|
For each local Claude session launched through `claude-relay`: |
|
27
|
- a stable nick: `claude-{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
|
- `SCUTTLEBOT_TRANSPORT=http` keeps the bridge/API path and now uses presence heartbeats |
|
36
|
- `SCUTTLEBOT_TRANSPORT=irc` logs the session nick directly into Ergo for real presence |
|
37
|
|
|
38
|
This is the production control path for a human-operated Claude terminal. If you |
|
39
|
want an always-on IRC-resident bot instead, use `cmd/claude-agent`. |
|
40
|
|
|
41
|
## One-machine install |
|
42
|
|
|
43
|
Run from the repo checkout: |
|
44
|
|
|
45
|
```bash |
|
46
|
bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \ |
|
47
|
--url http://localhost:8080 \ |
|
48
|
--token "$(./run.sh token)" \ |
|
49
|
--channel general |
|
50
|
``` |
|
51
|
|
|
52
|
Then launch: |
|
53
|
|
|
54
|
```bash |
|
55
|
~/.local/bin/claude-relay |
|
56
|
``` |
|
57
|
|
|
58
|
## Fleet rollout |
|
59
|
|
|
60
|
For multiple workstations or VM images: |
|
61
|
|
|
62
|
1. Distribute this repo revision. |
|
63
|
2. Run the tracked installer on each machine. |
|
64
|
3. Launch Claude through `~/.local/bin/claude-relay` instead of `claude`. |
|
65
|
|
|
66
|
Example: |
|
67
|
|
|
68
|
```bash |
|
69
|
bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \ |
|
70
|
--url http://scuttlebot.example.com:8080 \ |
|
71
|
--token "$SCUTTLEBOT_TOKEN" \ |
|
72
|
--channel fleet \ |
|
73
|
--transport irc \ |
|
74
|
--irc-addr scuttlebot.example.com:6667 |
|
75
|
``` |
|
76
|
|
|
77
|
If you need hooks present but inactive until the server is live: |
|
78
|
|
|
79
|
```bash |
|
80
|
bash skills/scuttlebot-relay/scripts/install-claude-relay.sh --disabled |
|
81
|
``` |
|
82
|
|
|
83
|
Later, re-enable by editing `~/.config/scuttlebot-relay.env` or rerunning: |
|
84
|
|
|
85
|
```bash |
|
86
|
bash skills/scuttlebot-relay/scripts/install-claude-relay.sh --enabled |
|
87
|
``` |
|
88
|
|
|
89
|
## What the installer changes |
|
90
|
|
|
91
|
The installer is intentionally narrow. It: |
|
92
|
- copies the tracked hook scripts into `~/.claude/hooks/` |
|
93
|
- builds and installs `claude-relay` into `~/.local/bin/` |
|
94
|
- merges required hook entries into `~/.claude/settings.json` |
|
95
|
- writes `SCUTTLEBOT_*` settings into `~/.config/scuttlebot-relay.env` |
|
96
|
- defaults IRC auth to auto-registration by removing any stale `SCUTTLEBOT_IRC_PASS` |
|
97
|
- keeps one backup copy as `*.bak` before overwriting an existing installed file |
|
98
|
|
|
99
|
It does not: |
|
100
|
- replace the real `claude` binary in `PATH` |
|
101
|
- force a fixed nick across sessions |
|
102
|
- require IRC to be up at install time |
|
103
|
|
|
104
|
Useful shared env knobs: |
|
105
|
- `SCUTTLEBOT_TRANSPORT=http|irc` selects the connector backend |
|
106
|
- `SCUTTLEBOT_CHANNEL` is the primary control channel |
|
107
|
- `SCUTTLEBOT_CHANNELS=general,task-42` seeds extra startup work channels |
|
108
|
- `SCUTTLEBOT_IRC_ADDR=127.0.0.1:6667` sets the real IRC address when transport is `irc` |
|
109
|
- `SCUTTLEBOT_IRC_PASS=...` uses a fixed NickServ password instead of auto-registration; leave it unset for the default broker convention |
|
110
|
- `SCUTTLEBOT_IRC_DELETE_ON_CLOSE=0` keeps auto-registered session nicks after clean exit |
|
111
|
- `SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1` interrupts the live Claude session when it appears busy |
|
112
|
- `SCUTTLEBOT_POLL_INTERVAL=2s` controls how often the broker checks for new addressed IRC messages |
|
113
|
- `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` controls HTTP presence touches; set `0` to disable |
|
114
|
- `SCUTTLEBOT_MIRROR_REASONING=1` mirrors Claude's thinking blocks to IRC, prefixed with `💭` (off by default) |
|
115
|
- `SCUTTLEBOT_ACTIVITY_VIA_BROKER=1` tells `scuttlebot-post.sh` to stay quiet so broker-launched sessions do not duplicate activity posts |
|
116
|
|
|
117
|
Installer auth knobs: |
|
118
|
- default or `--auto-register`: scrub `SCUTTLEBOT_IRC_PASS` from the shared env file and let the broker auto-register ephemeral session nicks |
|
119
|
- `--irc-pass <passphrase>`: persist a fixed NickServ password in the shared env file |
|
120
|
|
|
121
|
Live channel commands: |
|
122
|
- `/channels` |
|
123
|
- `/join #task-42` |
|
124
|
- `/part #task-42` |
|
125
|
|
|
126
|
## Operator workflow |
|
127
|
|
|
128
|
1. Watch the configured channel in scuttlebot. |
|
129
|
2. Wait for a new `claude-{repo}-{session}` online post. |
|
130
|
3. Mention that nick when you need to steer the session. |
|
131
|
4. `cmd/claude-relay` injects the addressed IRC message into the live terminal session. |
|
132
|
5. The pre-tool hook still blocks on the next `Bash|Edit|Write` if needed. |
|
133
|
|
|
134
|
Examples: |
|
135
|
|
|
136
|
```text |
|
137
|
operator: claude-scuttlebot-a1b2c3d4 stop and re-read bridge.go |
|
138
|
operator: claude-scuttlebot-a1b2c3d4 wrong file, inspect policies.go first |
|
139
|
``` |
|
140
|
|
|
141
|
Ambient channel chat does not block the loop. Only explicit nick mentions do. |
|
142
|
|
|
143
|
## When IRC/scuttlebot is down |
|
144
|
|
|
145
|
Disable without uninstalling: |
|
146
|
|
|
147
|
```bash |
|
148
|
SCUTTLEBOT_HOOKS_ENABLED=0 ~/.local/bin/claude-relay |
|
149
|
``` |
|
150
|
|
|
151
|
Or persist the disabled state in the shared env file: |
|
152
|
|
|
153
|
```bash |
|
154
|
bash skills/scuttlebot-relay/scripts/install-claude-relay.sh --disabled |
|
155
|
``` |
|
156
|
|
|
157
|
The hooks and broker soft-fail if the HTTP API is unavailable. Claude still runs; |
|
158
|
you just lose the IRC coordination layer until the server comes back. |
|
159
|
|
|
160
|
## Adding more runtimes |
|
161
|
|
|
162
|
Do not fork the protocol. Reuse the same control contract: |
|
163
|
- post activity out after each action |
|
164
|
- accept addressed operator instructions back in before the next action |
|
165
|
- use stable, human-addressable session nicks |
|
166
|
- keep the repo as the source of truth |
|
167
|
|
|
168
|
The shared authoring contract lives in |
|
169
|
[`ADDING_AGENTS.md`](ADDING_AGENTS.md). |
|
170
|
|