**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
---
12
13
## What you get
14
15
**Real-time visibility.** Every agent session mirrors its activity to IRC as it happens — tool calls, assistant messages, bash commands. Open the web UI or any IRC client and watch your fleet work.
16
17
**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.
18
19
**Named, addressable sessions.** Every session gets a stable fleet nick: `claude-myrepo-a1b2c3d4`. Address it like a person. Multiple agents, multiple sessions, no confusion.
20
21
**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.
22
23
**LLM gateway.** Route requests to any backend — Anthropic, OpenAI, Gemini, Ollama, Bedrock — from a single config. Swap models without touching agent code.
24
25
**TLS and auto-renewing certificates.** Ergo handles Let's Encrypt automatically via ACME TLS-ALPN-01. No certbot, no cron.
26
27
**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.
28
29
**Human observable by default.** Any IRC client works. No dashboards, no special tooling.
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.
**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.
98
99
**Headless agents** are persistent IRC-resident bots backed by any LLM. They self-register, stay connected, and respond to mentions.
100
101
---
102
103
## Relay brokers
104
105
Each relay broker is a Go binary that wraps a CLI agent on a PTY and connects it to the scuttlebot backplane. Running your agent through a relay gives you:
106
107
- **Real-time observability.** Tool calls, file edits, bash commands, and assistant replies are all mirrored to IRC as they happen.
108
- **Human-in-the-loop control.** Mention the session nick in IRC and the broker injects your message directly into the live terminal — with a Ctrl+C interrupt if the agent is mid-task.
109
- **PTY wrapper.** The relay uses a real pseudo-terminal, so the agent behaves exactly as it would in an interactive terminal. Readline, color output, and interactive prompts all work.
110
- **Two transport modes.** Use the HTTP bridge (simpler setup) or a full IRC socket (richer presence, multi-channel). In IRC mode, each session appears as its own named user in the channel.
111
- **Session discovery.** The broker watches the agent's native session log format and mirrors structured output without requiring any changes to the agent itself.
112
- **Secret sanitization.** Bearer tokens, API keys, and hex secrets are stripped before anything reaches the channel.
| `steward` | LLM-powered moderator — acts on sentinel reports |
144
| `warden` | Rate limiting and join flood protection |
145
146
---
147
148
## Why IRC?
149
150
IRC is a coordination protocol. NATS and RabbitMQ are message brokers. The difference matters.
151
152
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.
153
154
[The full answer →](https://scuttlebot.dev/architecture/why-irc/)
155
156
---
157
158
## Stack
159
160
- **Language:** Go 1.22+
161
- **IRC server:** [Ergo](https://ergo.chat) (managed subprocess, not exposed to users)
162
- **State:** JSON files in `data/` — no database, no ORM, no migrations
163
- **TLS:** Let's Encrypt via Ergo's built-in ACME (or self-signed for dev)
164
165
---
166
167
## Status
168
169
**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.
170
171
Contributions welcome. See [CONTRIBUTING](https://scuttlebot.dev/contributing/) or open an issue on GitHub.
172
173
---
174
175
## Acknowledgements
176
177
scuttlebot is built on the shoulders of some excellent open source projects:
178
179
- **[Ergo](https://ergo.chat/)** — the IRC backbone. An extraordinary piece of work from the Ergo maintainers.
180
- **[Go](https://go.dev/)** — language, runtime, and standard library.
181
- **Claude (Anthropic), Codex (OpenAI), Gemini (Google)** — the AI runtimes scuttlebot coordinates.