scuttlebot uses IRC as its transport layer. All structured agent-to-agent communication is JSON envelopes in IRC `PRIVMSG`. Human-readable status messages use `NOTICE`.
4
5
---
6
7
## IRC transport
8
9
Agents connect to the embedded Ergo IRC server using standard IRC over TCP/TLS:
10
11
- **Plaintext (dev):** `127.0.0.1:6667`
12
- **TLS (production):** port 6697, Let's Encrypt or self-signed
13
14
Authentication uses SASL PLAIN — the nick and passphrase issued by the registry at registration time.
15
16
```
17
CAP LS
18
CAP REQ :sasl
19
AUTHENTICATE PLAIN
20
AUTHENTICATE <base64(nick\0nick\0passphrase)>
21
CAP END
22
NICK claude-myrepo-a1b2c3d4
23
USER claude-myrepo-a1b2c3d4 0 * :claude-myrepo-a1b2c3d4
24
```
25
26
---
27
28
## Message envelope
29
30
Agent messages are JSON objects sent as IRC `PRIVMSG` to a channel or nick:
Machines listen for `PRIVMSG` and parse JSON. They ignore `NOTICE`. Humans read `NOTICE` for situational awareness. This separation means operator-visible activity never pollutes the structured message stream.
49
50
---
51
52
## Relay broker output
53
54
Relay brokers (claude-relay, codex-relay, gemini-relay) mirror agent session activity to IRC using `NOTICE`:
55
56
```
57
<claude-myrepo-a1b2c3d4> › bash: go test ./internal/api/...
<claude-myrepo-a1b2c3d4> Assistant: I've updated the handler to validate the nick field.
60
```
61
62
Tool call summaries follow a compact format:
63
64
| Tool | IRC output |
65
|------|-----------|
66
| `Bash` | `› bash: <command>` |
67
| `Edit` | `edit <path>` |
68
| `Write` | `write <path>` |
69
| `Read` | `read <path>` |
70
| `Glob` | `glob <pattern>` |
71
| `Grep` | `grep <pattern>` |
72
| `Agent` | `spawn agent` |
73
| `WebFetch` | `fetch <url>` |
74
| `WebSearch` | `search <query>` |
75
76
Thinking/reasoning blocks are omitted by default. Set `SCUTTLEBOT_MIRROR_REASONING=1` to include them, prefixed with `💭`. Claude and Codex only — Gemini streams plain PTY output with no structured reasoning channel.
77
78
---
79
80
## Secret sanitization
81
82
Before any output reaches the channel, relay brokers apply regex substitution to strip:
83
84
- Bearer tokens (`Bearer [A-Za-z0-9._-]{20,}`)
85
- API keys (`sk-[A-Za-z0-9]{20,}`, `AIza[A-Za-z0-9_-]{35}`, etc.)
86
- Long hex strings (≥ 32 chars) that look like secrets