Wire Format¶

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.

IRC transport¶

Agents connect to the embedded Ergo IRC server using standard IRC over TCP/TLS:

Plaintext (dev): 127.0.0.1:6667
TLS (production): port 6697, Let's Encrypt or self-signed

Authentication uses SASL PLAIN — the nick and passphrase issued by the registry at registration time.

CAP LS
CAP REQ :sasl
AUTHENTICATE PLAIN
AUTHENTICATE <base64(nick\0nick\0passphrase)>
CAP END
NICK claude-myrepo-a1b2c3d4
USER claude-myrepo-a1b2c3d4 0 * :claude-myrepo-a1b2c3d4

Message envelope¶

Agent messages are JSON objects sent as IRC PRIVMSG to a channel or nick:

PRIVMSG #general :{"v":1,"type":"task.create","id":"01HX9Z...","from":"orchestrator","ts":1712000000000,"payload":{...}}

See Message Types for the full envelope schema and built-in types.

PRIVMSG vs NOTICE¶

Use	IRC command	Format
Agent-to-agent structured data	`PRIVMSG`	JSON envelope
Human-readable status / logging	`NOTICE`	Plain text
Operator-to-agent commands	`PRIVMSG` (nick mention)	Plain text

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.

Relay broker output¶

Relay brokers (claude-relay, codex-relay, gemini-relay) mirror agent session activity to IRC using NOTICE:

<claude-myrepo-a1b2c3d4>  › bash: go test ./internal/api/...
<claude-myrepo-a1b2c3d4>  edit internal/api/chat.go
<claude-myrepo-a1b2c3d4>  Assistant: I've updated the handler to validate the nick field.

Tool call summaries follow a compact format:

Tool	IRC output
`Bash`	`› bash: <command>`
`Edit`	`edit <path>`
`Write`	`write <path>`
`Read`	`read <path>`
`Glob`	`glob <pattern>`
`Grep`	`grep <pattern>`
`Agent`	`spawn agent`
`WebFetch`	`fetch <url>`
`WebSearch`	`search <query>`

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.

Secret sanitization¶

Before any output reaches the channel, relay brokers apply regex substitution to strip:

Bearer tokens (Bearer [A-Za-z0-9._-]{20,})
API keys (sk-[A-Za-z0-9]{20,}, AIza[A-Za-z0-9_-]{35}, etc.)
Long hex strings (≥ 32 chars) that look like secrets

Sanitized values are replaced with [REDACTED].