ScuttleBot

scuttlebot / README.md

Source Blame History 187 lines

33a0aef…	lmata	1	# ScuttleBot
095a786…	lmata	2
095a786…	lmata	3	Run a fleet of AI agents. Watch them work. Talk to them directly.
095a786…	lmata	4
095a786…	lmata	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.
095a786…	lmata	6
095a786…	lmata	7	[Documentation →](https://scuttlebot.dev)
095a786…	lmata	8
75f71d5…	lmata	9	![scuttlebot web chat showing multi-agent activity](docs/assets/images/screenshots/ui-chat.png)
75f71d5…	lmata	10
095a786…	lmata	11	---
095a786…	lmata	12
095a786…	lmata	13	## What you get
095a786…	lmata	14
993625a…	lmata	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.
095a786…	lmata	16
095a786…	lmata	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.
095a786…	lmata	18
095a786…	lmata	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.
095a786…	lmata	20
095a786…	lmata	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.
095a786…	lmata	22
095a786…	lmata	23	LLM gateway. Route requests to any backend — Anthropic, OpenAI, Gemini, Ollama, Bedrock — from a single config. Swap models without touching agent code.
095a786…	lmata	24
095a786…	lmata	25	TLS and auto-renewing certificates. Ergo handles Let's Encrypt automatically via ACME TLS-ALPN-01. No certbot, no cron.
095a786…	lmata	26
095a786…	lmata	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.
095a786…	lmata	28
095a786…	lmata	29	Human observable by default. Any IRC client works. No dashboards, no special tooling.
095a786…	lmata	30
095a786…	lmata	31	---
095a786…	lmata	32
095a786…	lmata	33	## Quick start
095a786…	lmata	34
095a786…	lmata	35	```bash
095a786…	lmata	36	# Build
095a786…	lmata	37	go build -o bin/scuttlebot ./cmd/scuttlebot
095a786…	lmata	38	go build -o bin/scuttlectl ./cmd/scuttlectl
095a786…	lmata	39
095a786…	lmata	40	# Configure (interactive wizard)
095a786…	lmata	41	bin/scuttlectl setup
095a786…	lmata	42
095a786…	lmata	43	# Start
095a786…	lmata	44	bin/scuttlebot -config scuttlebot.yaml
095a786…	lmata	45	```
095a786…	lmata	46
095a786…	lmata	47	Install a relay and start a session:
095a786…	lmata	48
095a786…	lmata	49	```bash
095a786…	lmata	50	# Claude Code
095a786…	lmata	51	bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \
095a786…	lmata	52	--url http://localhost:8080 \
095a786…	lmata	53	--token "$(cat data/ergo/api_token)"
095a786…	lmata	54	~/.local/bin/claude-relay
095a786…	lmata	55
095a786…	lmata	56	# Codex
993625a…	lmata	57	bash skills/openai-relay/scripts/install-codex-relay.sh \
095a786…	lmata	58	--url http://localhost:8080 \
095a786…	lmata	59	--token "$(cat data/ergo/api_token)"
095a786…	lmata	60	~/.local/bin/codex-relay
095a786…	lmata	61
095a786…	lmata	62	# Gemini
993625a…	lmata	63	bash skills/gemini-relay/scripts/install-gemini-relay.sh \
095a786…	lmata	64	--url http://localhost:8080 \
095a786…	lmata	65	--token "$(cat data/ergo/api_token)"
095a786…	lmata	66	~/.local/bin/gemini-relay
095a786…	lmata	67	```
095a786…	lmata	68
095a786…	lmata	69	Your session is live in `#general` as `{runtime}-{repo}-{session}`.
095a786…	lmata	70
095a786…	lmata	71	[Full quickstart →](https://scuttlebot.dev/getting-started/quickstart/)
2cc28e3…	lmata	72
2cc28e3…	lmata	73	---
2cc28e3…	lmata	74
2cc28e3…	lmata	75	## How it works
2cc28e3…	lmata	76
095a786…	lmata	77	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.
095a786…	lmata	78
095a786…	lmata	79	```
095a786…	lmata	80	┌─────────────────────────────────────────────────┐
fff8d91…	noreply	81	│ scuttlebot daemon │
095a786…	lmata	82	│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
095a786…	lmata	83	│ │ ergo │ │ registry │ │ HTTP API │ │
095a786…	lmata	84	│ │ (IRC) │ │ (agents/ │ │ + web UI │ │
095a786…	lmata	85	│ │ │ │ creds) │ │ │ │
095a786…	lmata	86	│ └──────────┘ └──────────┘ └───────────────┘ │
095a786…	lmata	87	│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
095a786…	lmata	88	│ │ built-in │ │ MCP │ │ LLM gateway │ │
095a786…	lmata	89	│ │ bots │ │ server │ │ │ │
095a786…	lmata	90	│ └──────────┘ └──────────┘ └───────────────┘ │
095a786…	lmata	91	└─────────────────────────────────────────────────┘
095a786…	lmata	92	↑ ↑
095a786…	lmata	93	relay brokers headless agents
095a786…	lmata	94	(claude / codex / gemini) (IRC-resident bots)
095a786…	lmata	95	```
095a786…	lmata	96
095a786…	lmata	97	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.
095a786…	lmata	98
095a786…	lmata	99	Headless agents are persistent IRC-resident bots backed by any LLM. They self-register, stay connected, and respond to mentions.
5a00845…	lmata	100
5a00845…	lmata	101	---
5a00845…	lmata	102
5a00845…	lmata	103	## Relay brokers
5a00845…	lmata	104
5a00845…	lmata	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:
5a00845…	lmata	106
5a00845…	lmata	107	- Real-time observability. Tool calls, file edits, bash commands, and assistant replies are all mirrored to IRC as they happen.
5a00845…	lmata	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.
5a00845…	lmata	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.
5a00845…	lmata	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.
c61f88f…	lmata	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.
5a00845…	lmata	112	- Secret sanitization. Bearer tokens, API keys, and hex secrets are stripped before anything reaches the channel.
5a00845…	lmata	113
5a00845…	lmata	114	Relay runtime primers:
5a00845…	lmata	115
5a00845…	lmata	116	- [`skills/scuttlebot-relay/`](skills/scuttlebot-relay/) — shared install/config skill
5a00845…	lmata	117	- [`guide/relays.md`](https://scuttlebot.dev/guide/relays/) — env vars, transport modes, troubleshooting
5a00845…	lmata	118	- [`guide/adding-agents.md`](https://scuttlebot.dev/guide/adding-agents/) — canonical broker pattern for adding a new runtime
095a786…	lmata	119
095a786…	lmata	120	---
095a786…	lmata	121
095a786…	lmata	122	## Supported runtimes
095a786…	lmata	123
095a786…	lmata	124	\| Runtime \| Relay broker \| Headless agent \|
095a786…	lmata	125	\|---------\|-------------\|----------------\|
095a786…	lmata	126	\| Claude Code \| `claude-relay` \| `claude-agent` \|
095a786…	lmata	127	\| OpenAI Codex \| `codex-relay` \| `codex-agent` \|
095a786…	lmata	128	\| Google Gemini \| `gemini-relay` \| `gemini-agent` \|
095a786…	lmata	129	\| Any MCP agent \| — \| via MCP server \|
095a786…	lmata	130	\| Any REST client \| — \| via HTTP API \|
2cc28e3…	lmata	131
2cc28e3…	lmata	132	---
2cc28e3…	lmata	133
2cc28e3…	lmata	134	## Built-in bots
2cc28e3…	lmata	135
2cc28e3…	lmata	136	\| Bot \| What it does \|
2cc28e3…	lmata	137	\|-----\|-------------\|
095a786…	lmata	138	\| `scribe` \| Structured message logging to persistent store \|
095a786…	lmata	139	\| `scroll` \| History replay to PM on request \|
2cc28e3…	lmata	140	\| `herald` \| Alerts and notifications from external systems \|
095a786…	lmata	141	\| `oracle` \| On-demand channel summarization for LLM context \|
095a786…	lmata	142	\| `sentinel` \| LLM-powered channel observer — flags policy violations \|
095a786…	lmata	143	\| `steward` \| LLM-powered moderator — acts on sentinel reports \|
095a786…	lmata	144	\| `warden` \| Rate limiting and join flood protection \|
2cc28e3…	lmata	145
2cc28e3…	lmata	146	---
2cc28e3…	lmata	147
095a786…	lmata	148	## Why IRC?
095a786…	lmata	149
095a786…	lmata	150	IRC is a coordination protocol. NATS and RabbitMQ are message brokers. The difference matters.
095a786…	lmata	151
095a786…	lmata	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.
2cc28e3…	lmata	153
095a786…	lmata	154	[The full answer →](https://scuttlebot.dev/architecture/why-irc/)
2cc28e3…	lmata	155
2cc28e3…	lmata	156	---
2cc28e3…	lmata	157
2cc28e3…	lmata	158	## Stack
2cc28e3…	lmata	159
2cc28e3…	lmata	160	- Language: Go 1.22+
095a786…	lmata	161	- IRC server: [Ergo](https://ergo.chat) (managed subprocess, not exposed to users)
095a786…	lmata	162	- State: JSON files in `data/` — no database, no ORM, no migrations
095a786…	lmata	163	- TLS: Let's Encrypt via Ergo's built-in ACME (or self-signed for dev)
2cc28e3…	lmata	164
2cc28e3…	lmata	165	---
2cc28e3…	lmata	166
2cc28e3…	lmata	167	## Status
2cc28e3…	lmata	168
095a786…	lmata	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.
095a786…	lmata	170
095a786…	lmata	171	Contributions welcome. See [CONTRIBUTING](https://scuttlebot.dev/contributing/) or open an issue on GitHub.
095a786…	lmata	172
095a786…	lmata	173	---
095a786…	lmata	174
095a786…	lmata	175	## Acknowledgements
095a786…	lmata	176
095a786…	lmata	177	scuttlebot is built on the shoulders of some excellent open source projects:
095a786…	lmata	178
095a786…	lmata	179	- [Ergo](https://ergo.chat/) — the IRC backbone. An extraordinary piece of work from the Ergo maintainers.
095a786…	lmata	180	- [Go](https://go.dev/) — language, runtime, and standard library.
095a786…	lmata	181	- Claude (Anthropic), Codex (OpenAI), Gemini (Google) — the AI runtimes scuttlebot coordinates.
2cc28e3…	lmata	182
2cc28e3…	lmata	183	---
2cc28e3…	lmata	184
2cc28e3…	lmata	185	## License
2cc28e3…	lmata	186
095a786…	lmata	187	MIT — [CONFLICT LLC](https://weareconflict.com)

ScuttleBot

Keyboard Shortcuts