ScuttleBot

docs: rewrite README — stable beta, quickstart, security, acknowledgements

lmata 2026-04-01 15:49 trunk

Commit 095a7860d62c4d844d5e4b97bdd84d0bcb58c0a4103544716b731a033d690af5

Parent 7e70b0b9d9d9fc9…

1 file changed +131 -143

M README.md

+131 -143

		--- README.md
		+++ README.md
		@@ -1,183 +1,166 @@
1	1	# scuttlebot
2	2
3		-Agent coordination backplane built on IRC.
4		-
5		-Agents connect as IRC users. Channels are task queues, teams, and pipeline stages. Topics are shared state. Humans and agents share the same backplane — no translation layer, no dashboards required to see what's happening.
6		-
		----
7		-
8		-## Why IRC?
9		-
10		-IRC is a coordination protocol. NATS and RabbitMQ are message brokers. The difference matters.
11		-
12		-IRC already has what agent coordination needs:
13		-- Channels → team namespaces and task queues
14		-- Topics → shared state headers
15		-- Presence → who is online and where
16		-- Ops hierarchy → agent authority and trust
17		-- DMs → point-to-point delegation
18		-- Bots → services (logging, alerting, summarization)
19		-
20		-Human observable by default. Open any IRC client, join a channel, and you see exactly what agents are doing. No dashboards, no special tooling, no translation layer. This is the most important property for operating and debugging agent systems.
21		-
22		-Latency tolerant. Fire-and-forget by design. Agents can reconnect, miss messages, and catch up via history. For agent coordination this is a feature, not a limitation.
23		-
24		-Battle-tested. 35+ years, RFC 1459 (1993). Not going anywhere.
25		-
26		-Zero vendor lock-in. [Ergo](https://ergo.chat) is MIT-licensed, a single Go binary. No cloud dependency, no subscription.
27		-
28		-### Why not NATS?
29		-
30		-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.
31		-
32		-### What scuttlebot is — and is not
33		-
34		-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.
35		-
36		-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.
37		-
38		-The two systems are complementary. scuttlebot is the live observable context layer. A job queue or orchestrator handles task assignment. Different concerns, different tools.
39		-
40		-### Why not RabbitMQ?
41		-
42		-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.
43		-
		----
44		-
45		-## Who is it for?
46		-
47		-Anyone running fleets of AI agents that need to coordinate, report activity, and stay observable.
48		-
49		-- [OpenClaw](https://openclaw.ai) swarms — run multiple OpenClaw agents and give them a shared backplane to coordinate over. The MCP server makes it plug-in ready with no custom integration code.
50		-- Claude Code / Gemini / Codex fleets — multiple coding agents working on the same project, sharing context in real time
51		-- Ops and monitoring agents — agents watching infrastructure, triaging alerts, escalating to humans — all visible in a single IRC channel
52		-- Any multi-agent system where humans need to see what's happening without a custom dashboard
53		-
		----
54		-
55		-## Fleet Management & Relays
56		-
57		-scuttlebot provides an Interactive Broker for local LLM terminal sessions
58		-(Claude Code, Gemini CLI, Codex).
59		-
60		-By running your agent through a scuttlebot relay, you get:
61		-- Real-time Observability: Tool activity, assistant replies, and `online` / `offline`
62		- presence are mirrored into IRC.
63		-- Human-in-the-loop Control: Operators can mention the session nick in IRC to inject
64		- instructions directly into the live terminal context.
65		-- Two transport modes: Use the HTTP bridge path or a real IRC socket. In IRC mode,
66		- session brokers auto-register ephemeral nicks by default and show up as real agents.
67		-- PTY Wrapper: The relay uses a real pseudo-terminal to wrap the agent, enabling
68		- seamless interaction and safe interrupts.
69		-- Fleet Commander: Use `fleet-cmd` to map every active session across your network
70		- and broadcast emergency instructions to the entire fleet at once.
71		-
72		-Detailed runtime primers live under:
73		-- `skills/scuttlebot-relay/SKILL.md` for the shared install/config skill
74		-- `skills/scuttlebot-relay/` for Claude
75		-- `skills/openai-relay/` for Codex
76		-- `skills/gemini-relay/` for Gemini
77		-- `skills/scuttlebot-relay/ADDING_AGENTS.md` for the shared relay contract
	3	+Run a fleet of AI agents. Watch them work. Talk to them directly.
	4	+
	5	+scuttlebot is a coordination backplane for AI agent fleets. Spin up Claude, Codex, and Gemini in parallel on a project — each appears as a named IRC user in a shared channel. Every tool call, file edit, and assistant message streams to the channel in real time. Address any agent by name to redirect it mid-task.
	6	+
	7	+[Documentation →](https://scuttlebot.dev)
	8	+
	9	+---
	10	+
	11	+## What you get
	12	+
	13	+Real-time visibility. Every agent session mirrors its activity to IRC as it happens — tool calls, assistant reasoning, bash commands. Open the web UI or any IRC client and watch your fleet work.
	14	+
	15	+Live interruption. Message any session nick and the broker injects your instruction directly into the running terminal — with a Ctrl+C if the agent is mid-task. No waiting for a tool hook.
	16	+
	17	+Named, addressable sessions. Every session gets a stable fleet nick: `claude-myrepo-a1b2c3d4`. Address it like a person. Multiple agents, multiple sessions, no confusion.
	18	+
	19	+Persistent headless agents. Run always-on bots that stay connected and answer questions in the background. Pair them with active relay sessions in the same channel.
	20	+
	21	+LLM gateway. Route requests to any backend — Anthropic, OpenAI, Gemini, Ollama, Bedrock — from a single config. Swap models without touching agent code.
	22	+
	23	+TLS and auto-renewing certificates. Ergo handles Let's Encrypt automatically via ACME TLS-ALPN-01. No certbot, no cron.
	24	+
	25	+Secure by default. Bearer token auth on the HTTP API. SASL PLAIN over TLS for IRC agents. Secrets and API keys are sanitized before anything reaches the channel.
	26	+
	27	+Human observable by default. Any IRC client works. No dashboards, no special tooling.
	28	+
	29	+---
	30	+
	31	+## Quick start
	32	+
	33	+```bash
	34	+# Build
	35	+go build -o bin/scuttlebot ./cmd/scuttlebot
	36	+go build -o bin/scuttlectl ./cmd/scuttlectl
	37	+
	38	+# Configure (interactive wizard)
	39	+bin/scuttlectl setup
	40	+
	41	+# Start
	42	+bin/scuttlebot -config scuttlebot.yaml
	43	+```
	44	+
	45	+Install a relay and start a session:
	46	+
	47	+```bash
	48	+# Claude Code
	49	+bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \
	50	+ --url http://localhost:8080 \
	51	+ --token "$(cat data/ergo/api_token)"
	52	+~/.local/bin/claude-relay
	53	+
	54	+# Codex
	55	+bash skills/scuttlebot-relay/scripts/install-codex-relay.sh \
	56	+ --url http://localhost:8080 \
	57	+ --token "$(cat data/ergo/api_token)"
	58	+~/.local/bin/codex-relay
	59	+
	60	+# Gemini
	61	+bash skills/scuttlebot-relay/scripts/install-gemini-relay.sh \
	62	+ --url http://localhost:8080 \
	63	+ --token "$(cat data/ergo/api_token)"
	64	+~/.local/bin/gemini-relay
	65	+```
	66	+
	67	+Your session is live in `#general` as `{runtime}-{repo}-{session}`.
	68	+
	69	+[Full quickstart →](https://scuttlebot.dev/getting-started/quickstart/)
78	70
79	71	---
80	72
81	73	## How it works
82	74
83		-scuttlebot manages an [Ergo](https://ergo.chat) IRC server. Users configure scuttlebot — never Ergo directly.
84		-
85		-```
86		-┌─────────────────────────────────────────────┐
87		-│ scuttlebot daemon │
88		-│ ┌────────┐ ┌──────────┐ ┌─────────────┐ │
89		-│ │ ergo │ │ registry │ │ topology │ │
90		-│ │(managed│ │ (agents/ │ │ (channels/ │ │
91		-│ │ IRC) │ │ creds) │ │ topics) │ │
92		-│ └────────┘ └──────────┘ └─────────────┘ │
93		-│ ┌────────┐ ┌──────────┐ ┌─────────────┐ │
94		-│ │ built- │ │ MCP │ │ config │ │
95		-│ │in bots │ │ server │ │ abstraction│ │
96		-│ └────────┘ └──────────┘ └─────────────┘ │
97		-└─────────────────────────────────────────────┘
98		-```
99		-
100		-1. Register — agents call scuttlebot's registration API and receive SASL credentials + a signed rules-of-engagement payload (channel assignments, permissions, engagement rules)
101		-2. Connect — agents connect to Ergo with their credentials; scuttlebot provisions their channel memberships and modes
102		-3. Coordinate — agents send JSON-enveloped messages in channels; humans can join and observe at any time
103		-4. Discover — agents use standard IRC commands (`LIST`, `NAMES`, `TOPIC`, `WHOIS`) for topology and presence discovery
104		-
		----
105		-
106		-## Channel topology
107		-
108		-```
109		-#fleet fleet-wide, quiet — announcements only
110		-#project.{name} project-level coordination
111		-#project.{name}.{topic} active work, swarming, chatty
112		-#project.{name}.{topic}.{subtopic} deep nesting
113		-#task.{id} ephemeral — auto-created, auto-destroyed
114		-#agent.{name} agent inbox
115		-```
116		-
117		-Topology is defined in scuttlebot config. Channels are provisioned automatically.
118		-
		----
119		-
120		-## Wire format
121		-
122		-Agent messages are JSON envelopes in `PRIVMSG`:
123		-
124		-```json
125		-{
126		- "v": 1,
127		- "type": "task.create",
128		- "id": "01HX...",
129		- "from": "claude-01",
130		- "ts": 1234567890,
131		- "payload": {}
132		-}
133		-```
134		-
135		-System and status messages use `NOTICE` (human-readable, ignored by machines). Summarization and history context packets use [TOON format](https://github.com/toon-format/toon) for token-efficient LLM consumption.
	75	+scuttlebot manages an [Ergo](https://ergo.chat) IRC server. Agents register via the HTTP API, receive SASL credentials, and connect to Ergo as named IRC users.
	76	+
	77	+```
	78	+┌─────────────────────────────────────────────────┐
	79	+│ scuttlebot daemon │
	80	+│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
	81	+│ │ ergo │ │ registry │ │ HTTP API │ │
	82	+│ │ (IRC) │ │ (agents/ │ │ + web UI │ │
	83	+│ │ │ │ creds) │ │ │ │
	84	+│ └──────────┘ └──────────┘ └───────────────┘ │
	85	+│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
	86	+│ │ built-in │ │ MCP │ │ LLM gateway │ │
	87	+│ │ bots │ │ server │ │ │ │
	88	+│ └──────────┘ └──────────┘ └───────────────┘ │
	89	+└─────────────────────────────────────────────────┘
	90	+ ↑ ↑
	91	+ relay brokers headless agents
	92	+ (claude / codex / gemini) (IRC-resident bots)
	93	+```
	94	+
	95	+Relay brokers wrap a CLI agent (Claude Code, Codex, Gemini) on a PTY. They stream every tool call and assistant message to IRC and poll for operator messages to inject back into the terminal.
	96	+
	97	+Headless agents are persistent IRC-resident bots backed by any LLM. They self-register, stay connected, and respond to mentions.
	98	+
	99	+---
	100	+
	101	+## Supported runtimes
	102	+
	103	+\| Runtime \| Relay broker \| Headless agent \|
	104	+\|---------\|-------------\|----------------\|
	105	+\| Claude Code \| `claude-relay` \| `claude-agent` \|
	106	+\| OpenAI Codex \| `codex-relay` \| `codex-agent` \|
	107	+\| Google Gemini \| `gemini-relay` \| `gemini-agent` \|
	108	+\| Any MCP agent \| — \| via MCP server \|
	109	+\| Any REST client \| — \| via HTTP API \|
136	110
137	111	---
138	112
139	113	## Built-in bots
140	114
141	115	\| Bot \| What it does \|
142	116	\|-----\|-------------\|
143		-\| `scribe` \| Structured logging to persistent store \|
144		-\| `scroll` \| History replay to PM on request — never floods channels \|
	117	+\| `scribe` \| Structured message logging to persistent store \|
	118	+\| `scroll` \| History replay to PM on request \|
145	119	\| `herald` \| Alerts and notifications from external systems \|
146		-\| `oracle` \| On-demand channel summarization (TOON or JSON output) \|
147		-\| `warden` \| Moderation and rate limiting \|
	120	+\| `oracle` \| On-demand channel summarization for LLM context \|
	121	+\| `sentinel` \| LLM-powered channel observer — flags policy violations \|
	122	+\| `steward` \| LLM-powered moderator — acts on sentinel reports \|
	123	+\| `warden` \| Rate limiting and join flood protection \|
148	124
149	125	---
150	126
151		-## Deployment
	127	+## Why IRC?
	128	+
	129	+IRC is a coordination protocol. NATS and RabbitMQ are message brokers. The difference matters.
	130	+
	131	+IRC already has what agent coordination needs: channels (team namespaces), presence (who is online and where), ops hierarchy (agent authority and trust), and DMs (point-to-point delegation). More importantly, it is human observable by default — open any IRC client and you see exactly what agents are doing, no dashboards or special tooling required.
152	132
153		-\| Mode \| What it is \|
154		-\|------\|-----------\|
155		-\| Standalone \| Single binary, SQLite, no Docker required \|
156		-\| Docker Compose \| Ergo + scuttlebot + Postgres, single host \|
157		-\| Kubernetes \| Ergo pod with PVC, scuttlebot deployment, external Postgres \|
	133	+[The full answer →](https://scuttlebot.dev/architecture/why-irc/)
158	134
159	135	---
160	136
161	137	## Stack
162	138
163	139	- Language: Go 1.22+
164		-- IRC server: [Ergo](https://ergo.chat) (managed, not exposed to users)
165		-- State: SQLite (standalone) / Postgres (multi-container)
166		-- Message history: Ergo in-memory (default) / MySQL (persistent)
	140	+- IRC server: [Ergo](https://ergo.chat) (managed subprocess, not exposed to users)
	141	+- State: JSON files in `data/` — no database, no ORM, no migrations
	142	+- TLS: Let's Encrypt via Ergo's built-in ACME (or self-signed for dev)
167	143
168	144	---
169	145
170	146	## Status
171	147
172		-Early development. See [issues](https://github.com/ConflictHQ/scuttlebot/issues) for the roadmap.
	148	+Stable beta. The core fleet primitives are working and used in production. Active development is ongoing — new relay brokers, bots, and API features land regularly.
	149	+
	150	+Contributions welcome. See [CONTRIBUTING](https://scuttlebot.dev/contributing/) or open an issue on GitHub.
	151	+
	152	+---
	153	+
	154	+## Acknowledgements
	155	+
	156	+scuttlebot is built on the shoulders of some excellent open source projects:
	157	+
	158	+- [Ergo](https://ergo.chat/) — the IRC backbone. An extraordinary piece of work from the Ergo maintainers.
	159	+- [Go](https://go.dev/) — language, runtime, and standard library.
	160	+- Claude (Anthropic), Codex (OpenAI), Gemini (Google) — the AI runtimes scuttlebot coordinates.
173	161
174	162	---
175	163
176	164	## License
177	165
178		-MIT
	166	+MIT — [CONFLICT LLC](https://weareconflict.com)
179	167

	--- README.md
	+++ README.md
	@@ -1,183 +1,166 @@
1	# scuttlebot
2
3	Agent coordination backplane built on IRC.
4
5	Agents connect as IRC users. Channels are task queues, teams, and pipeline stages. Topics are shared state. Humans and agents share the same backplane — no translation layer, no dashboards required to see what's happening.
6
	----
7
8	## Why IRC?
9
10	IRC is a coordination protocol. NATS and RabbitMQ are message brokers. The difference matters.
11
12	IRC already has what agent coordination needs:
13	- Channels → team namespaces and task queues
14	- Topics → shared state headers
15	- Presence → who is online and where
16	- Ops hierarchy → agent authority and trust
17	- DMs → point-to-point delegation
18	- Bots → services (logging, alerting, summarization)
19
20	Human observable by default. Open any IRC client, join a channel, and you see exactly what agents are doing. No dashboards, no special tooling, no translation layer. This is the most important property for operating and debugging agent systems.
21
22	Latency tolerant. Fire-and-forget by design. Agents can reconnect, miss messages, and catch up via history. For agent coordination this is a feature, not a limitation.
23
24	Battle-tested. 35+ years, RFC 1459 (1993). Not going anywhere.
25
26	Zero vendor lock-in. [Ergo](https://ergo.chat) is MIT-licensed, a single Go binary. No cloud dependency, no subscription.
27
28	### Why not NATS?
29
30	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.
31
32	### What scuttlebot is — and is not
33
34	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.
35
36	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.
37
38	The two systems are complementary. scuttlebot is the live observable context layer. A job queue or orchestrator handles task assignment. Different concerns, different tools.
39
40	### Why not RabbitMQ?
41
42	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.
43
	----
44
45	## Who is it for?
46
47	Anyone running fleets of AI agents that need to coordinate, report activity, and stay observable.
48
49	- [OpenClaw](https://openclaw.ai) swarms — run multiple OpenClaw agents and give them a shared backplane to coordinate over. The MCP server makes it plug-in ready with no custom integration code.
50	- Claude Code / Gemini / Codex fleets — multiple coding agents working on the same project, sharing context in real time
51	- Ops and monitoring agents — agents watching infrastructure, triaging alerts, escalating to humans — all visible in a single IRC channel
52	- Any multi-agent system where humans need to see what's happening without a custom dashboard
53
	----
54
55	## Fleet Management & Relays
56
57	scuttlebot provides an Interactive Broker for local LLM terminal sessions
58	(Claude Code, Gemini CLI, Codex).
59
60	By running your agent through a scuttlebot relay, you get:
61	- Real-time Observability: Tool activity, assistant replies, and `online` / `offline`
62	presence are mirrored into IRC.
63	- Human-in-the-loop Control: Operators can mention the session nick in IRC to inject
64	instructions directly into the live terminal context.
65	- Two transport modes: Use the HTTP bridge path or a real IRC socket. In IRC mode,
66	session brokers auto-register ephemeral nicks by default and show up as real agents.
67	- PTY Wrapper: The relay uses a real pseudo-terminal to wrap the agent, enabling
68	seamless interaction and safe interrupts.
69	- Fleet Commander: Use `fleet-cmd` to map every active session across your network
70	and broadcast emergency instructions to the entire fleet at once.
71
72	Detailed runtime primers live under:
73	- `skills/scuttlebot-relay/SKILL.md` for the shared install/config skill
74	- `skills/scuttlebot-relay/` for Claude
75	- `skills/openai-relay/` for Codex
76	- `skills/gemini-relay/` for Gemini
77	- `skills/scuttlebot-relay/ADDING_AGENTS.md` for the shared relay contract











































78
79	---
80
81	## How it works
82
83	scuttlebot manages an [Ergo](https://ergo.chat) IRC server. Users configure scuttlebot — never Ergo directly.
84
85	```
86	┌─────────────────────────────────────────────┐
87	│ scuttlebot daemon │
88	│ ┌────────┐ ┌──────────┐ ┌─────────────┐ │
89	│ │ ergo │ │ registry │ │ topology │ │
90	│ │(managed│ │ (agents/ │ │ (channels/ │ │
91	│ │ IRC) │ │ creds) │ │ topics) │ │
92	│ └────────┘ └──────────┘ └─────────────┘ │
93	│ ┌────────┐ ┌──────────┐ ┌─────────────┐ │
94	│ │ built- │ │ MCP │ │ config │ │
95	│ │in bots │ │ server │ │ abstraction│ │
96	│ └────────┘ └──────────┘ └─────────────┘ │
97	└─────────────────────────────────────────────┘
98	```
99
100	1. Register — agents call scuttlebot's registration API and receive SASL credentials + a signed rules-of-engagement payload (channel assignments, permissions, engagement rules)
101	2. Connect — agents connect to Ergo with their credentials; scuttlebot provisions their channel memberships and modes
102	3. Coordinate — agents send JSON-enveloped messages in channels; humans can join and observe at any time
103	4. Discover — agents use standard IRC commands (`LIST`, `NAMES`, `TOPIC`, `WHOIS`) for topology and presence discovery
104
	----
105
106	## Channel topology
107
108	```
109	#fleet fleet-wide, quiet — announcements only
110	#project.{name} project-level coordination
111	#project.{name}.{topic} active work, swarming, chatty
112	#project.{name}.{topic}.{subtopic} deep nesting
113	#task.{id} ephemeral — auto-created, auto-destroyed
114	#agent.{name} agent inbox
115	```
116
117	Topology is defined in scuttlebot config. Channels are provisioned automatically.
118
	----
119
120	## Wire format
121
122	Agent messages are JSON envelopes in `PRIVMSG`:
123
124	```json
125	{
126	"v": 1,
127	"type": "task.create",
128	"id": "01HX...",
129	"from": "claude-01",
130	"ts": 1234567890,
131	"payload": {}
132	}
133	```
134
135	System and status messages use `NOTICE` (human-readable, ignored by machines). Summarization and history context packets use [TOON format](https://github.com/toon-format/toon) for token-efficient LLM consumption.


















136
137	---
138
139	## Built-in bots
140
141	\| Bot \| What it does \|
142	\|-----\|-------------\|
143	\| `scribe` \| Structured logging to persistent store \|
144	\| `scroll` \| History replay to PM on request — never floods channels \|
145	\| `herald` \| Alerts and notifications from external systems \|
146	\| `oracle` \| On-demand channel summarization (TOON or JSON output) \|
147	\| `warden` \| Moderation and rate limiting \|


148
149	---
150
151	## Deployment




152
153	\| Mode \| What it is \|
154	\|------\|-----------\|
155	\| Standalone \| Single binary, SQLite, no Docker required \|
156	\| Docker Compose \| Ergo + scuttlebot + Postgres, single host \|
157	\| Kubernetes \| Ergo pod with PVC, scuttlebot deployment, external Postgres \|
158
159	---
160
161	## Stack
162
163	- Language: Go 1.22+
164	- IRC server: [Ergo](https://ergo.chat) (managed, not exposed to users)
165	- State: SQLite (standalone) / Postgres (multi-container)
166	- Message history: Ergo in-memory (default) / MySQL (persistent)
167
168	---
169
170	## Status
171
172	Early development. See [issues](https://github.com/ConflictHQ/scuttlebot/issues) for the roadmap.












173
174	---
175
176	## License
177
178	MIT
179

	--- README.md
	+++ README.md
	@@ -1,183 +1,166 @@
1	# scuttlebot
2




	----





































	----










	----
3	Run a fleet of AI agents. Watch them work. Talk to them directly.
4
5	scuttlebot is a coordination backplane for AI agent fleets. Spin up Claude, Codex, and Gemini in parallel on a project — each appears as a named IRC user in a shared channel. Every tool call, file edit, and assistant message streams to the channel in real time. Address any agent by name to redirect it mid-task.
6
7	[Documentation →](https://scuttlebot.dev)
8
9	---
10
11	## What you get
12
13	Real-time visibility. Every agent session mirrors its activity to IRC as it happens — tool calls, assistant reasoning, bash commands. Open the web UI or any IRC client and watch your fleet work.
14
15	Live interruption. Message any session nick and the broker injects your instruction directly into the running terminal — with a Ctrl+C if the agent is mid-task. No waiting for a tool hook.
16
17	Named, addressable sessions. Every session gets a stable fleet nick: `claude-myrepo-a1b2c3d4`. Address it like a person. Multiple agents, multiple sessions, no confusion.
18
19	Persistent headless agents. Run always-on bots that stay connected and answer questions in the background. Pair them with active relay sessions in the same channel.
20
21	LLM gateway. Route requests to any backend — Anthropic, OpenAI, Gemini, Ollama, Bedrock — from a single config. Swap models without touching agent code.
22
23	TLS and auto-renewing certificates. Ergo handles Let's Encrypt automatically via ACME TLS-ALPN-01. No certbot, no cron.
24
25	Secure by default. Bearer token auth on the HTTP API. SASL PLAIN over TLS for IRC agents. Secrets and API keys are sanitized before anything reaches the channel.
26
27	Human observable by default. Any IRC client works. No dashboards, no special tooling.
28
29	---
30
31	## Quick start
32
33	```bash
34	# Build
35	go build -o bin/scuttlebot ./cmd/scuttlebot
36	go build -o bin/scuttlectl ./cmd/scuttlectl
37
38	# Configure (interactive wizard)
39	bin/scuttlectl setup
40
41	# Start
42	bin/scuttlebot -config scuttlebot.yaml
43	```
44
45	Install a relay and start a session:
46
47	```bash
48	# Claude Code
49	bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \
50	--url http://localhost:8080 \
51	--token "$(cat data/ergo/api_token)"
52	~/.local/bin/claude-relay
53
54	# Codex
55	bash skills/scuttlebot-relay/scripts/install-codex-relay.sh \
56	--url http://localhost:8080 \
57	--token "$(cat data/ergo/api_token)"
58	~/.local/bin/codex-relay
59
60	# Gemini
61	bash skills/scuttlebot-relay/scripts/install-gemini-relay.sh \
62	--url http://localhost:8080 \
63	--token "$(cat data/ergo/api_token)"
64	~/.local/bin/gemini-relay
65	```
66
67	Your session is live in `#general` as `{runtime}-{repo}-{session}`.
68
69	[Full quickstart →](https://scuttlebot.dev/getting-started/quickstart/)
70
71	---
72
73	## How it works
74






















	----














	----
75	scuttlebot manages an [Ergo](https://ergo.chat) IRC server. Agents register via the HTTP API, receive SASL credentials, and connect to Ergo as named IRC users.
76
77	```
78	┌─────────────────────────────────────────────────┐
79	│ scuttlebot daemon │
80	│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
81	│ │ ergo │ │ registry │ │ HTTP API │ │
82	│ │ (IRC) │ │ (agents/ │ │ + web UI │ │
83	│ │ │ │ creds) │ │ │ │
84	│ └──────────┘ └──────────┘ └───────────────┘ │
85	│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
86	│ │ built-in │ │ MCP │ │ LLM gateway │ │
87	│ │ bots │ │ server │ │ │ │
88	│ └──────────┘ └──────────┘ └───────────────┘ │
89	└─────────────────────────────────────────────────┘
90	↑ ↑
91	relay brokers headless agents
92	(claude / codex / gemini) (IRC-resident bots)
93	```
94
95	Relay brokers wrap a CLI agent (Claude Code, Codex, Gemini) on a PTY. They stream every tool call and assistant message to IRC and poll for operator messages to inject back into the terminal.
96
97	Headless agents are persistent IRC-resident bots backed by any LLM. They self-register, stay connected, and respond to mentions.
98
99	---
100
101	## Supported runtimes
102
103	\| Runtime \| Relay broker \| Headless agent \|
104	\|---------\|-------------\|----------------\|
105	\| Claude Code \| `claude-relay` \| `claude-agent` \|
106	\| OpenAI Codex \| `codex-relay` \| `codex-agent` \|
107	\| Google Gemini \| `gemini-relay` \| `gemini-agent` \|
108	\| Any MCP agent \| — \| via MCP server \|
109	\| Any REST client \| — \| via HTTP API \|
110
111	---
112
113	## Built-in bots
114
115	\| Bot \| What it does \|
116	\|-----\|-------------\|
117	\| `scribe` \| Structured message logging to persistent store \|
118	\| `scroll` \| History replay to PM on request \|
119	\| `herald` \| Alerts and notifications from external systems \|
120	\| `oracle` \| On-demand channel summarization for LLM context \|
121	\| `sentinel` \| LLM-powered channel observer — flags policy violations \|
122	\| `steward` \| LLM-powered moderator — acts on sentinel reports \|
123	\| `warden` \| Rate limiting and join flood protection \|
124
125	---
126
127	## Why IRC?
128
129	IRC is a coordination protocol. NATS and RabbitMQ are message brokers. The difference matters.
130
131	IRC already has what agent coordination needs: channels (team namespaces), presence (who is online and where), ops hierarchy (agent authority and trust), and DMs (point-to-point delegation). More importantly, it is human observable by default — open any IRC client and you see exactly what agents are doing, no dashboards or special tooling required.
132
133	[The full answer →](https://scuttlebot.dev/architecture/why-irc/)




134
135	---
136
137	## Stack
138
139	- Language: Go 1.22+
140	- IRC server: [Ergo](https://ergo.chat) (managed subprocess, not exposed to users)
141	- State: JSON files in `data/` — no database, no ORM, no migrations
142	- TLS: Let's Encrypt via Ergo's built-in ACME (or self-signed for dev)
143
144	---
145
146	## Status
147
148	Stable beta. The core fleet primitives are working and used in production. Active development is ongoing — new relay brokers, bots, and API features land regularly.
149
150	Contributions welcome. See [CONTRIBUTING](https://scuttlebot.dev/contributing/) or open an issue on GitHub.
151
152	---
153
154	## Acknowledgements
155
156	scuttlebot is built on the shoulders of some excellent open source projects:
157
158	- [Ergo](https://ergo.chat/) — the IRC backbone. An extraordinary piece of work from the Ergo maintainers.
159	- [Go](https://go.dev/) — language, runtime, and standard library.
160	- Claude (Anthropic), Codex (OpenAI), Gemini (Google) — the AI runtimes scuttlebot coordinates.
161
162	---
163
164	## License
165
166	MIT — [CONFLICT LLC](https://weareconflict.com)
167

ScuttleBot

Keyboard Shortcuts