ScuttleBot

docs: add IRC vs NATS/RabbitMQ rationale and update persistence/topology notes

lmata 2026-03-31 04:18 trunk

Commit 1ab586b1f28c3a13b5ccf1108f7bc8eca4534abc081ecb832bd0ebe322ffd5f2

Parent 6d0d615b1762037…

1 file changed +37

M bootstrap.md

+37

		--- bootstrap.md
		+++ bootstrap.md
		@@ -2,10 +2,47 @@
2	2
3	3	This is the primary conventions document. All agent shims (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `calliope.md`) point here.
4	4
5	5	An agent given this document and a business requirement should be able to generate correct, idiomatic code without exploring the codebase.
6	6
	7	+---
	8	+
	9	+## Why IRC (and not NATS or RabbitMQ)
	10	+
	11	+The short answer: IRC is a coordination protocol. NATS and RabbitMQ are message brokers. The difference matters.
	12	+
	13	+### IRC
	14	+
	15	+IRC has presence, identity, channels, topics, ops hierarchy, DMs, and bots — natively. These map directly to agent coordination concepts without bolting anything on. A channel is a team. A topic is shared state. Ops are authority. Bots are services. It all just works.
	16	+
	17	+It is also human observable by default. No dashboards, no special tooling, no translation layer. Open any IRC client, join a channel, and you see exactly what agents are doing. This is the single biggest advantage for debugging and operating agent systems.
	18	+
	19	+Other properties that matter for agent coordination:
	20	+- Latency tolerant — fire-and-forget, designed for unreliable networks. Agents can reconnect, miss messages, catch up via history. This is a feature, not a limitation.
	21	+- Battle-tested — 35+ years, RFC 1459 (1993), proven at scale. Not going anywhere.
	22	+- Self-hostable, zero vendor lock-in — Ergo is MIT, single Go binary. No cloud, no subscription.
	23	+- Bots are a solved problem — NickServ, ChanServ, BotServ, 35 years of tooling. We inherit all of it.
	24	+- Simple enough to debug naked — the protocol is plain text. When something breaks, you can read it.
	25	+
	26	+### Why not NATS
	27	+
	28	+NATS is excellent and fast. It is the right choice when you need guaranteed delivery, high-throughput pub/sub, or JetStream persistence at scale. It is not the right choice here because:
	29	+
	30	+- No native presence model — you cannot `WHOIS` a subject or see who is subscribed to a stream
	31	+- No ops hierarchy — authority and trust are not protocol concepts
	32	+- Not human observable without NATS-specific tooling (no standard client exists for "just watching")
	33	+- More moving pieces — JetStream, clustering, leaf nodes, consumers, streams. Powerful but not simple.
	34	+- The subject hierarchy (`project.myapp.tasks`) is conceptually identical to our channel naming convention — if we ever needed to swap, the mapping is straightforward
	35	+
	36	+### Why not RabbitMQ
	37	+
	38	+RabbitMQ is a serious enterprise message broker designed for guaranteed delivery workflows. It is operationally heavy (Erlang runtime, clustering, exchanges, bindings, queues), not human observable without a management UI, and not designed for real-time coordination between actors. Wrong tool for this job.
	39	+
	40	+### Swappability
	41	+
	42	+The JSON envelope format and the SDK abstraction (`pkg/client/`) are intentionally transport-agnostic. The channel naming convention maps cleanly to NATS subjects. If a use case demands NATS-level throughput or delivery guarantees, swapping the transport is a backend concern that does not affect the agent-facing API.
	43	+
7	44	---
8	45
9	46	## What is scuttlebot
10	47
11	48	An agent coordination backplane built on IRC. Agents connect as IRC users, coordinate via channels, and communicate via structured messages. IRC is an implementation detail — users configure scuttlebot, never Ergo directly.
12	49

	--- bootstrap.md
	+++ bootstrap.md
	@@ -2,10 +2,47 @@
2
3	This is the primary conventions document. All agent shims (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `calliope.md`) point here.
4
5	An agent given this document and a business requirement should be able to generate correct, idiomatic code without exploring the codebase.
6





































7	---
8
9	## What is scuttlebot
10
11	An agent coordination backplane built on IRC. Agents connect as IRC users, coordinate via channels, and communicate via structured messages. IRC is an implementation detail — users configure scuttlebot, never Ergo directly.
12

	--- bootstrap.md
	+++ bootstrap.md
	@@ -2,10 +2,47 @@
2
3	This is the primary conventions document. All agent shims (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `calliope.md`) point here.
4
5	An agent given this document and a business requirement should be able to generate correct, idiomatic code without exploring the codebase.
6
7	---
8
9	## Why IRC (and not NATS or RabbitMQ)
10
11	The short answer: IRC is a coordination protocol. NATS and RabbitMQ are message brokers. The difference matters.
12
13	### IRC
14
15	IRC has presence, identity, channels, topics, ops hierarchy, DMs, and bots — natively. These map directly to agent coordination concepts without bolting anything on. A channel is a team. A topic is shared state. Ops are authority. Bots are services. It all just works.
16
17	It is also human observable by default. No dashboards, no special tooling, no translation layer. Open any IRC client, join a channel, and you see exactly what agents are doing. This is the single biggest advantage for debugging and operating agent systems.
18
19	Other properties that matter for agent coordination:
20	- Latency tolerant — fire-and-forget, designed for unreliable networks. Agents can reconnect, miss messages, catch up via history. This is a feature, not a limitation.
21	- Battle-tested — 35+ years, RFC 1459 (1993), proven at scale. Not going anywhere.
22	- Self-hostable, zero vendor lock-in — Ergo is MIT, single Go binary. No cloud, no subscription.
23	- Bots are a solved problem — NickServ, ChanServ, BotServ, 35 years of tooling. We inherit all of it.
24	- Simple enough to debug naked — the protocol is plain text. When something breaks, you can read it.
25
26	### Why not NATS
27
28	NATS is excellent and fast. It is the right choice when you need guaranteed delivery, high-throughput pub/sub, or JetStream persistence at scale. It is not the right choice here because:
29
30	- No native presence model — you cannot `WHOIS` a subject or see who is subscribed to a stream
31	- No ops hierarchy — authority and trust are not protocol concepts
32	- Not human observable without NATS-specific tooling (no standard client exists for "just watching")
33	- More moving pieces — JetStream, clustering, leaf nodes, consumers, streams. Powerful but not simple.
34	- The subject hierarchy (`project.myapp.tasks`) is conceptually identical to our channel naming convention — if we ever needed to swap, the mapping is straightforward
35
36	### Why not RabbitMQ
37
38	RabbitMQ is a serious enterprise message broker designed for guaranteed delivery workflows. It is operationally heavy (Erlang runtime, clustering, exchanges, bindings, queues), not human observable without a management UI, and not designed for real-time coordination between actors. Wrong tool for this job.
39
40	### Swappability
41
42	The JSON envelope format and the SDK abstraction (`pkg/client/`) are intentionally transport-agnostic. The channel naming convention maps cleanly to NATS subjects. If a use case demands NATS-level throughput or delivery guarantees, swapping the transport is a backend concern that does not affect the agent-facing API.
43
44	---
45
46	## What is scuttlebot
47
48	An agent coordination backplane built on IRC. Agents connect as IRC users, coordinate via channels, and communicate via structured messages. IRC is an implementation detail — users configure scuttlebot, never Ergo directly.
49

ScuttleBot

Keyboard Shortcuts