ScuttleBot

scuttlebot / docs / architecture / why-irc.md
Source Blame History 106 lines
974ed6a… lmata 1 # Why IRC?
974ed6a… lmata 2
974ed6a… lmata 3 ## The short answer
974ed6a… lmata 4
974ed6a… lmata 5 IRC is a coordination protocol. NATS and RabbitMQ are message brokers. The difference matters.
974ed6a… lmata 6
974ed6a… lmata 7 Agent coordination needs: channels, topics, presence, identity, ops hierarchy, DMs, and bots. IRC has all of these natively. You don't bolt them on — they're part of the protocol.
974ed6a… lmata 8
974ed6a… lmata 9 ---
974ed6a… lmata 10
974ed6a… lmata 11 ## Human observable by default
974ed6a… lmata 12
974ed6a… lmata 13 This is the single most important property.
974ed6a… lmata 14
974ed6a… lmata 15 Open any IRC client, join a channel, and you see exactly what agents are doing. No dashboards. No special tooling. No translation layer. Humans and agents share the same backplane — an agent's activity is readable by any person with an IRC client and channel access.
974ed6a… lmata 16
974ed6a… lmata 17 When something goes wrong, you join the channel. That's it.
974ed6a… lmata 18
974ed6a… lmata 19 ---
974ed6a… lmata 20
974ed6a… lmata 21 ## Coordination primitives map directly
974ed6a… lmata 22
974ed6a… lmata 23 | Coordination concept | IRC primitive |
974ed6a… lmata 24 |---------------------|--------------|
974ed6a… lmata 25 | Team namespace | Channel (`#project.myapp.tasks`) |
974ed6a… lmata 26 | Shared state header | Topic |
974ed6a… lmata 27 | Who is active | Presence (`NAMES`, `WHOIS`) |
974ed6a… lmata 28 | Authority / trust | Ops hierarchy (`+o`, `+v`) |
974ed6a… lmata 29 | Point-to-point delegation | DM |
974ed6a… lmata 30 | Services (logging, alerting, summarization) | Bots |
974ed6a… lmata 31 | Fleet-wide announcement | `#fleet` channel |
974ed6a… lmata 32
974ed6a… lmata 33 Nothing is invented. Everything is already in the protocol.
974ed6a… lmata 34
974ed6a… lmata 35 ---
974ed6a… lmata 36
974ed6a… lmata 37 ## Latency tolerant
974ed6a… lmata 38
974ed6a… lmata 39 IRC is fire-and-forget, designed for unreliable networks. Agents can reconnect, miss messages, and catch up via history. For agent coordination — where agents may be slow, retrying, or temporarily offline — this is a feature, not a limitation.
974ed6a… lmata 40
974ed6a… lmata 41 ---
974ed6a… lmata 42
974ed6a… lmata 43 ## Battle-tested
974ed6a… lmata 44
974ed6a… lmata 45 35+ years. RFC 1459 (1993). Proven at scale across millions of concurrent users. The protocol is not going anywhere.
974ed6a… lmata 46
974ed6a… lmata 47 ---
974ed6a… lmata 48
974ed6a… lmata 49 ## Self-hostable, zero vendor lock-in
974ed6a… lmata 50
974ed6a… lmata 51 [Ergo](https://ergo.chat) is MIT-licensed and ships as a single Go binary. No cloud dependency, no subscription, no account. Run it anywhere.
974ed6a… lmata 52
974ed6a… lmata 53 ---
974ed6a… lmata 54
974ed6a… lmata 55 ## Bots are a solved problem
974ed6a… lmata 56
974ed6a… lmata 57 35 years of IRC bot frameworks, plugins, and integrations. NickServ, ChanServ, BotServ, OperServ — all built into Ergo. scuttlebot inherits a mature ecosystem rather than building service infrastructure from scratch.
974ed6a… lmata 58
974ed6a… lmata 59 ---
974ed6a… lmata 60
974ed6a… lmata 61 ## Why not NATS?
974ed6a… lmata 62
974ed6a… lmata 63 [NATS](https://nats.io) is excellent for high-throughput pub/sub and guaranteed delivery at scale. It is not the right choice here because:
974ed6a… lmata 64
974ed6a… lmata 65 - **No presence model** — you cannot `WHOIS` a subject or see who is subscribed
974ed6a… lmata 66 - **No ops hierarchy** — authority and trust are not protocol-level concepts
974ed6a… lmata 67 - **Not human observable** — requires NATS-specific tooling to observe traffic
974ed6a… lmata 68 - **More moving pieces** — JetStream, clustering, leaf nodes, consumers, streams. Powerful but not simple.
974ed6a… lmata 69
974ed6a… lmata 70 The channel naming convention (`#project.myapp.tasks`) maps directly to NATS subjects (`project.myapp.tasks`). The SDK abstraction is transport-agnostic. If a future use case demands NATS-level throughput or guaranteed delivery, swapping the transport is a backend concern that does not affect the agent-facing API.
974ed6a… lmata 71
974ed6a… lmata 72 ---
974ed6a… lmata 73
974ed6a… lmata 74 ## Why not RabbitMQ?
974ed6a… lmata 75
974ed6a… lmata 76 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.
974ed6a… lmata 77
974ed6a… lmata 78 ---
974ed6a… lmata 79
bb06ddc… lmata 80 ## What scuttlebot is — and is not
bb06ddc… lmata 81
bb06ddc… lmata 82 **scuttlebot is a live context backplane.** Agents spin up, connect, broadcast state and activity to whoever is currently active, coordinate with peers, then disconnect. High connection churn is expected and fine. If an agent wasn't connected when a message was sent, it doesn't receive it. That is intentional — this is a live stream, not a queue.
bb06ddc… lmata 83
bb06ddc… lmata 84 **scuttlebot is not a task queue.** It does not assign work to agents, guarantee message delivery, or hold messages for offline consumers. Task assignment, workflow dispatch, and guaranteed delivery belong in a dedicated system (a job queue, an orchestrator, or yes — NATS).
bb06ddc… lmata 85
bb06ddc… lmata 86 ---
bb06ddc… lmata 87
bb06ddc… lmata 88 ## If you need NATS-like functionality
bb06ddc… lmata 89
bb06ddc… lmata 90 Use [NATS](https://nats.io). Seriously.
bb06ddc… lmata 91
bb06ddc… lmata 92 If you need:
bb06ddc… lmata 93 - **Guaranteed message delivery** — agents that receive messages even if they were offline when sent
bb06ddc… lmata 94 - **Task queues / work distribution** — one task, one worker, no double-processing
bb06ddc… lmata 95 - **Request/reply patterns** — synchronous-style RPC over messaging
bb06ddc… lmata 96 - **Durable consumers** — replay from a position in a stream
bb06ddc… lmata 97
bb06ddc… lmata 98 ...then NATS JetStream is the right tool and scuttlebot is not.
bb06ddc… lmata 99
bb06ddc… lmata 100 scuttlebot is for the *live context layer* — the shared situational awareness across a fleet of active agents, observable by humans in real time. NATS is for the *work distribution layer*. In a well-designed agent platform, you likely want both, doing different jobs.
bb06ddc… lmata 101
bb06ddc… lmata 102 ---
bb06ddc… lmata 103
974ed6a… lmata 104 ## The swappability principle
974ed6a… lmata 105
bb06ddc… lmata 106 scuttlebot's JSON message envelope and SDK abstraction are intentionally transport-agnostic. IRC is the default and the right choice for the target use case (private networks, live context, human observability required). The architecture does not preclude future transport backends.

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button