ScuttleBot

docs: add what scuttlebot is/is not, recommend NATS for task queue use cases

lmata 2026-03-31 04:29 trunk

Commit bb06ddc2c36404124767d1d46cbeacec89e6edb7a8731e7d6c8f939c7c9e4893

Parent 974ed6a02e3599b…

2 files changed +8 +25 -1

~ README.md ~ docs/architecture/why-irc.md

M README.md

		--- README.md
		+++ README.md
		@@ -28,10 +28,18 @@
28	28
29	29	### Why not NATS?
30	30
31	31	NATS is excellent for high-throughput pub/sub and guaranteed delivery. It is not the right choice here because there is no native presence model (you cannot see who is subscribed), no ops hierarchy, and it is not human observable without NATS-specific tooling. The channel naming convention (`#project.myapp.tasks`) maps directly to NATS subjects — if a future use case demands NATS throughput, swapping the transport is a backend concern that does not affect the agent API.
32	32
	33	+### What scuttlebot is — and is not
	34	+
	35	+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.
	36	+
	37	+scuttlebot is not a task queue. It does not assign work to agents, guarantee message delivery, or hold messages for offline consumers. If you need those things, use [NATS](https://nats.io) — it's excellent at them and scuttlebot is not trying to replace it.
	38	+
	39	+The two systems are complementary. scuttlebot is the live observable context layer. A job queue or orchestrator handles task assignment. Different concerns, different tools.
	40	+
33	41	### Why not RabbitMQ?
34	42
35	43	Wrong tool. RabbitMQ is designed for guaranteed delivery workflows. It is operationally heavy, not human observable without a management UI, and not designed for real-time coordination between actors.
36	44
37	45	---
38	46

	--- README.md
	+++ README.md
	@@ -28,10 +28,18 @@
28
29	### Why not NATS?
30
31	NATS is excellent for high-throughput pub/sub and guaranteed delivery. It is not the right choice here because there is no native presence model (you cannot see who is subscribed), no ops hierarchy, and it is not human observable without NATS-specific tooling. The channel naming convention (`#project.myapp.tasks`) maps directly to NATS subjects — if a future use case demands NATS throughput, swapping the transport is a backend concern that does not affect the agent API.
32








33	### Why not RabbitMQ?
34
35	Wrong tool. RabbitMQ is designed for guaranteed delivery workflows. It is operationally heavy, not human observable without a management UI, and not designed for real-time coordination between actors.
36
37	---
38

	--- README.md
	+++ README.md
	@@ -28,10 +28,18 @@
28
29	### Why not NATS?
30
31	NATS is excellent for high-throughput pub/sub and guaranteed delivery. It is not the right choice here because there is no native presence model (you cannot see who is subscribed), no ops hierarchy, and it is not human observable without NATS-specific tooling. The channel naming convention (`#project.myapp.tasks`) maps directly to NATS subjects — if a future use case demands NATS throughput, swapping the transport is a backend concern that does not affect the agent API.
32
33	### What scuttlebot is — and is not
34
35	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.
36
37	scuttlebot is not a task queue. It does not assign work to agents, guarantee message delivery, or hold messages for offline consumers. If you need those things, use [NATS](https://nats.io) — it's excellent at them and scuttlebot is not trying to replace it.
38
39	The two systems are complementary. scuttlebot is the live observable context layer. A job queue or orchestrator handles task assignment. Different concerns, different tools.
40
41	### Why not RabbitMQ?
42
43	Wrong tool. RabbitMQ is designed for guaranteed delivery workflows. It is operationally heavy, not human observable without a management UI, and not designed for real-time coordination between actors.
44
45	---
46

M docs/architecture/why-irc.md

+25 -1

		--- docs/architecture/why-irc.md
		+++ docs/architecture/why-irc.md
		@@ -74,9 +74,33 @@
74	74	## Why not RabbitMQ?
75	75
76	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.
77	77
78	78	---
	79	+
	80	+## What scuttlebot is — and is not
	81	+
	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.
	83	+
	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).
	85	+
	86	+---
	87	+
	88	+## If you need NATS-like functionality
	89	+
	90	+Use [NATS](https://nats.io). Seriously.
	91	+
	92	+If you need:
	93	+- Guaranteed message delivery — agents that receive messages even if they were offline when sent
	94	+- Task queues / work distribution — one task, one worker, no double-processing
	95	+- Request/reply patterns — synchronous-style RPC over messaging
	96	+- Durable consumers — replay from a position in a stream
	97	+
	98	+...then NATS JetStream is the right tool and scuttlebot is not.
	99	+
	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.
	101	+
	102	+---
79	103
80	104	## The swappability principle
81	105
82		-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, 100s–1000s of agents, human observability required). The architecture does not preclude future transport backends.
	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.
83	107

	--- docs/architecture/why-irc.md
	+++ docs/architecture/why-irc.md
	@@ -74,9 +74,33 @@
74	## Why not RabbitMQ?
75
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.
77
78	---
























79
80	## The swappability principle
81
82	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, 100s–1000s of agents, human observability required). The architecture does not preclude future transport backends.
83

	--- docs/architecture/why-irc.md
	+++ docs/architecture/why-irc.md
	@@ -74,9 +74,33 @@
74	## Why not RabbitMQ?
75
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.
77
78	---
79
80	## What scuttlebot is — and is not
81
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.
83
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).
85
86	---
87
88	## If you need NATS-like functionality
89
90	Use [NATS](https://nats.io). Seriously.
91
92	If you need:
93	- Guaranteed message delivery — agents that receive messages even if they were offline when sent
94	- Task queues / work distribution — one task, one worker, no double-processing
95	- Request/reply patterns — synchronous-style RPC over messaging
96	- Durable consumers — replay from a position in a stream
97
98	...then NATS JetStream is the right tool and scuttlebot is not.
99
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.
101
102	---
103
104	## The swappability principle
105
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.
107

ScuttleBot

Keyboard Shortcuts