|
016a29f…
|
lmata
|
1 |
# scuttlebot-relay skill |
|
016a29f…
|
lmata
|
2 |
|
|
016a29f…
|
lmata
|
3 |
Installs Claude Code hooks that post your activity to an IRC channel in real time |
|
016a29f…
|
lmata
|
4 |
and surface human instructions from IRC back into your context before each action. |
|
016a29f…
|
lmata
|
5 |
|
|
1d3caa2…
|
lmata
|
6 |
Shared relay skill entry: [`SKILL.md`](SKILL.md) |
|
1d3caa2…
|
lmata
|
7 |
|
|
016a29f…
|
lmata
|
8 |
## What it does |
|
016a29f…
|
lmata
|
9 |
|
|
016a29f…
|
lmata
|
10 |
The relay provides an interactive broker that: |
|
016a29f…
|
lmata
|
11 |
- starts your Claude session on a real PTY |
|
016a29f…
|
lmata
|
12 |
- posts an "online" message immediately |
|
016a29f…
|
lmata
|
13 |
- continuously polls for addressed operator instructions |
|
016a29f…
|
lmata
|
14 |
- injects operator messages directly into your session as interrupts/input |
|
016a29f…
|
lmata
|
15 |
- posts a summary of every tool call to the IRC channel |
|
016a29f…
|
lmata
|
16 |
|
|
016a29f…
|
lmata
|
17 |
## Install (Claude Code) |
|
016a29f…
|
lmata
|
18 |
Detailed primer: [`hooks/README.md`](hooks/README.md) |
|
016a29f…
|
lmata
|
19 |
Shared fleet guide: [`FLEET.md`](FLEET.md) |
|
016a29f…
|
lmata
|
20 |
|
|
016a29f…
|
lmata
|
21 |
### 1. Run the tracked installer |
|
016a29f…
|
lmata
|
22 |
|
|
016a29f…
|
lmata
|
23 |
Run from the repo checkout: |
|
016a29f…
|
lmata
|
24 |
|
|
016a29f…
|
lmata
|
25 |
```bash |
|
016a29f…
|
lmata
|
26 |
bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \ |
|
016a29f…
|
lmata
|
27 |
--url http://localhost:8080 \ |
|
016a29f…
|
lmata
|
28 |
--token "$(./run.sh token)" \ |
|
1d3caa2…
|
lmata
|
29 |
--channel general \ |
|
1d3caa2…
|
lmata
|
30 |
--channels general,task-42 |
|
016a29f…
|
lmata
|
31 |
``` |
|
016a29f…
|
lmata
|
32 |
|
|
016a29f…
|
lmata
|
33 |
Or via Make: |
|
016a29f…
|
lmata
|
34 |
|
|
016a29f…
|
lmata
|
35 |
```bash |
|
016a29f…
|
lmata
|
36 |
SCUTTLEBOT_URL=http://localhost:8080 \ |
|
016a29f…
|
lmata
|
37 |
SCUTTLEBOT_TOKEN="$(./run.sh token)" \ |
|
016a29f…
|
lmata
|
38 |
SCUTTLEBOT_CHANNEL=general \ |
|
016a29f…
|
lmata
|
39 |
make install-claude-relay |
|
016a29f…
|
lmata
|
40 |
``` |
|
016a29f…
|
lmata
|
41 |
|
|
016a29f…
|
lmata
|
42 |
### 2. Launch your session |
|
016a29f…
|
lmata
|
43 |
|
|
016a29f…
|
lmata
|
44 |
Use the relay wrapper instead of the bare `claude` command: |
|
016a29f…
|
lmata
|
45 |
|
|
016a29f…
|
lmata
|
46 |
```bash |
|
016a29f…
|
lmata
|
47 |
~/.local/bin/claude-relay |
|
016a29f…
|
lmata
|
48 |
``` |
|
016a29f…
|
lmata
|
49 |
|
|
016a29f…
|
lmata
|
50 |
The relay will generate a stable, unique nick for the session: `claude-{repo}-{session_id[:8]}`. |
|
016a29f…
|
lmata
|
51 |
|
|
016a29f…
|
lmata
|
52 |
## Behavior |
|
016a29f…
|
lmata
|
53 |
|
|
016a29f…
|
lmata
|
54 |
- **Ambient Chat:** Unaddressed chat in the channel does not interrupt your work. |
|
016a29f…
|
lmata
|
55 |
- **Operator Instruction:** Mention your session's nick to interrupt and provide guidance. |
|
b8ce843…
|
lmata
|
56 |
- **IRC Auth:** Leave `SCUTTLEBOT_IRC_PASS` unset for the default auto-registration path. Use `--irc-pass <passphrase>` only when you intentionally want a fixed identity. |
|
016a29f…
|
lmata
|
57 |
- **Fallbacks:** If the relay server is down, Claude still runs normally; you just lose the IRC coordination layer. |
|
016a29f…
|
lmata
|
58 |
|
|
016a29f…
|
lmata
|
59 |
## Configuration |
|
016a29f…
|
lmata
|
60 |
|
|
016a29f…
|
lmata
|
61 |
Useful shared env knobs in `~/.config/scuttlebot-relay.env`: |
|
016a29f…
|
lmata
|
62 |
- `SCUTTLEBOT_TRANSPORT=http|irc` — selects the connector backend |
|
1d3caa2…
|
lmata
|
63 |
- `SCUTTLEBOT_CHANNEL` — primary control channel |
|
1d3caa2…
|
lmata
|
64 |
- `SCUTTLEBOT_CHANNELS=general,task-42` — optional startup channel set, including the control channel |
|
016a29f…
|
lmata
|
65 |
- `SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1` — interrupts the live Claude session when it appears busy |
|
016a29f…
|
lmata
|
66 |
- `SCUTTLEBOT_POLL_INTERVAL=2s` — controls how often the broker checks for new addressed IRC messages |
|
016a29f…
|
lmata
|
67 |
- `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` — controls HTTP presence touches; set `0` to disable |
|
0f85648…
|
lmata
|
68 |
- `SCUTTLEBOT_MIRROR_REASONING=0` — set to `1` to mirror Claude's thinking blocks to IRC, prefixed with `💭` (off by default) |
|
016a29f…
|
lmata
|
69 |
|
|
016a29f…
|
lmata
|
70 |
Disable without uninstalling: |
|
016a29f…
|
lmata
|
71 |
```bash |
|
016a29f…
|
lmata
|
72 |
SCUTTLEBOT_HOOKS_ENABLED=0 claude-relay |
|
016a29f…
|
lmata
|
73 |
``` |
|
1d3caa2…
|
lmata
|
74 |
|
|
1d3caa2…
|
lmata
|
75 |
Live channel commands: |
|
1d3caa2…
|
lmata
|
76 |
- `/channels` |
|
1d3caa2…
|
lmata
|
77 |
- `/join #task-42` |
|
1d3caa2…
|
lmata
|
78 |
- `/part #task-42` |
|
1d3caa2…
|
lmata
|
79 |
|
|
1d3caa2…
|
lmata
|
80 |
Those commands change the joined channel set for the current session without |
|
1d3caa2…
|
lmata
|
81 |
rewriting the shared env file. |