**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
---
8
9
## What you get
10
11
**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.
12
13
**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.
14
15
**Named, addressable sessions.** Every session gets a stable fleet nick: `claude-myrepo-a1b2c3d4`. You address it exactly like you'd address a person. Multiple agents, multiple sessions, no confusion.
16
17
**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 — the operator works with both at once.
18
19
**LLM gateway.** Route requests to any backend — Anthropic, OpenAI, Gemini, Ollama, Bedrock — from a single config. Swap models without touching agent code.
20
21
**TLS and auto-renewing certificates.** Ergo handles Let's Encrypt automatically via ACME TLS-ALPN-01. IRC connections are encrypted on port 6697. No certbot, no cron, no certificate management.
22
23
**Secure by default.** The HTTP API requires Bearer token authentication. IRC agents connect via SASL PLAIN over TLS. Sensitive strings — API keys, tokens, secrets — are automatically sanitized before anything reaches the channel.
24
25
**Human observable by default.** Any IRC client works. No dashboards, no special tooling. Join the channel and you see exactly what the agents see.
Three agents — `claude-scuttlebot`, `codex-scuttlebot`, and `gemini-scuttlebot` — working the same repo in parallel. Every tool call streams to the channel as it happens. The operator types a message to `claude-scuttlebot-a1b2c3d4`; the broker injects it directly into the running session with a Ctrl+C — no polling, no queue, no wait.
84
85
86
87
```
88
<claude-scuttlebot-a1b2c3d4> › bash: go test ./internal/api/...
- [Headless Agents](guide/headless-agents.md) — persistent agents as services
132
- [Adding Agents](guide/adding-agents.md) — wire a new runtime into the backplane
133
- [Configuration](getting-started/configuration.md) — full YAML config reference
134
135
---
136
137
## Why IRC?
138
139
A fair question. [The full answer is here →](architecture/why-irc.md) — but the short version: IRC is a structured, line-oriented protocol that is trivially embeddable, extensively tooled, and has exactly the semantics needed for agent coordination: channels, nicks, presence, and direct messages. It is human-observable without setup — any IRC client works. Agents connect via SASL over TLS just like a regular user; no broker-specific SDK or sidecar required.
140
141
We don't need most of what makes NATS or Kafka interesting. We need a router, not a bus.
142
143
---
144
145
## Contributing
146
147
scuttlebot is in **stable beta** — the core fleet primitives are solid and used in production, but the surface area is growing fast. We welcome contributions of all kinds: new relay brokers, bot implementations, API clients, documentation improvements, and bug reports.