This is the primary conventions document. All agent shims (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `calliope.md`) point here.
4
5
An agent given this document and a business requirement should be able to generate correct, idiomatic code without exploring the codebase.
6
7
---
8
9
## Why IRC (and not NATS or RabbitMQ)
10
11
The short answer: IRC is a coordination protocol. NATS and RabbitMQ are message brokers. The difference matters.
12
13
### IRC
14
15
IRC has presence, identity, channels, topics, ops hierarchy, DMs, and bots — natively. These map directly to agent coordination concepts without bolting anything on. A channel is a team. A topic is shared state. Ops are authority. Bots are services. It all just works.
16
17
It is also **human observable by default**. No dashboards, no special tooling, no translation layer. Open any IRC client, join a channel, and you see exactly what agents are doing. This is the single biggest advantage for debugging and operating agent systems.
18
19
Other properties that matter for agent coordination:
20
- **Latency tolerant** — fire-and-forget, designed for unreliable networks. Agents can reconnect, miss messages, catch up via history. This is a feature, not a limitation.
21
- **Battle-tested** — 35+ years, RFC 1459 (1993), proven at scale. Not going anywhere.
22
- **Self-hostable, zero vendor lock-in** — Ergo is MIT, single Go binary. No cloud, no subscription.
23
- **Bots are a solved problem** — NickServ, ChanServ, BotServ, 35 years of tooling. We inherit all of it.
24
- **Simple enough to debug naked** — the protocol is plain text. When something breaks, you can read it.
25
26
### Why not NATS
27
28
NATS is excellent and fast. It is the right choice when you need guaranteed delivery, high-throughput pub/sub, or JetStream persistence at scale. It is not the right choice here because:
29
30
- No native presence model — you cannot `WHOIS` a subject or see who is subscribed to a stream
31
- No ops hierarchy — authority and trust are not protocol concepts
32
- Not human observable without NATS-specific tooling (no standard client exists for "just watching")
33
- More moving pieces — JetStream, clustering, leaf nodes, consumers, streams. Powerful but not simple.
34
- The subject hierarchy (`project.myapp.tasks`) is conceptually identical to our channel naming convention — if we ever needed to swap, the mapping is straightforward
35
36
### Why not RabbitMQ
37
38
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. Wrong tool for this job.
39
40
### Swappability
41
42
The JSON envelope format and the SDK abstraction (`pkg/client/`) are intentionally transport-agnostic. The channel naming convention maps cleanly to NATS subjects. If a use case demands NATS-level throughput or delivery guarantees, swapping the transport is a backend concern that does not affect the agent-facing API.
43
44
---
45
46
## What is scuttlebot
47
48
An agent coordination backplane built on IRC. Agents connect as IRC users, coordinate via channels, and communicate via structured messages. IRC is an implementation detail — users configure scuttlebot, never Ergo directly.
49
50
**Why IRC:** lightweight TCP transport, encryption, channels, presence, ops hierarchy, DMs, human observable by default. Humans and agents share the same backplane with no translation layer.
51
52
**Ergo** (https://ergo.chat) is the IRC server. scuttlebot manages its lifecycle and config. Federation, auth, history, TLS, rate limiting — all Ergo. scuttlebot abstracts it.
53
54
---
55
56
## Monorepo Layout
57
58
```
59
cmd/
60
scuttlebot/ # daemon binary
61
scuttlectl/ # admin CLI
62
internal/apiclient/ # typed API client used by scuttlectl
63
internal/
64
api/ # HTTP API server (Bearer auth) + embedded web UI at /ui/
65
ui/index.html # single-file operator web UI
66
auth/ # admin account store — bcrypt hashed, persisted to JSON
67
bots/
68
manager/ # bot lifecycle — starts/stops bots on policy change
Single Go module. All state persisted as JSON files under `data/` (no database required).
99
100
---
101
102
## Architecture
103
104
### Ergo relationship
105
106
scuttlebot owns the Ergo process and config. Users never edit `ircd.yaml` directly. scuttlebot generates it from its own config and manages Ergo as a subprocess.
107
108
- Ergo provides: TLS, SASL accounts, channel persistence, message history, ops hierarchy, server federation, rate limiting
All 10 bots are implemented. Enabled/configured via the web UI or `scuttlectl bot list`. The manager (`internal/bots/manager/`) starts/stops them dynamically when policies change. All bots set `+B` (bot) user mode on connect and auto-accept INVITE.
163
164
| Bot | Nick | Role |
165
|-----|------|------|
166
| `auditbot` | auditbot | Immutable append-only audit trail of agent actions and credential events |
Oracle uses TOON format (`pkg/toon/`) for token-efficient LLM context. Scroll supports `format=toon` for compact replay output. Configure `api_key_env` to the name of the env var holding the API key (e.g. `ORACLE_OPENAI_API_KEY`), and `base_url` for non-OpenAI providers.
178
179
### Scale
180
181
Target: 100s to low 1000s of agents on a private network. Single Ergo instance handles this comfortably (documented up to 10k clients, 2k per channel). Ergo scales up (multi-core), not out — no horizontal clustering today. Federation is planned upstream but has no timeline; not a scuttlebot concern for now.
182
183
### Persistence
184
185
No database required. All state is persisted as JSON files under `data/` by default.
API keys are per-consumer tokens with scoped permissions. Each key has a name, scopes, optional expiry, and last-used tracking. Scopes: `admin`, `agents`, `channels`, `chat`, `topology`, `bots`, `config`, `read`. The `admin` scope implies all others.
239
240
`POST /login` accepts `{username, password}` and returns a 24h session token with admin scope. Rate limited to 10 attempts per minute per IP.
241
242
On first run, the legacy `api_token` file is migrated into `api_keys.json` as the first admin-scope key. New keys are created via `POST /v1/api-keys`, `scuttlectl api-key create`, or the web UI settings tab.
243
244
Admin accounts managed via `scuttlectl admin` or web UI. First run auto-creates `admin` with a random password printed to the log.
245
246
### Key endpoints
247
248
All `/v1/` endpoints require a Bearer token with the appropriate scope.
1. Create `internal/bots/{name}/` package with a `Bot` struct and `Start(ctx context.Context) error` method
295
2. Set `+B` user mode on connect, handle INVITE for auto-join
296
3. Add a `BotSpec` config struct if the bot needs user-configurable settings
297
4. Register in `internal/bots/manager/manager.go`:
298
- Add a case to `buildBot()` that constructs your bot from the spec config
299
- Add a `BehaviorConfig` entry to `defaultBehaviors` in `internal/api/policies.go`
300
5. Add commands to `botCommands` map in `internal/api/policies.go` for the web UI command reference
301
6. Add the UI config schema to `BEHAVIOR_SCHEMAS` in `internal/api/ui/index.html`
302
7. Use `internal/bots/cmdparse/` for command routing if the bot accepts DM commands
303
8. Write tests: bot logic, config parsing, edge cases. IRC connection can be skipped in unit tests.
304
9. Update this bootstrap
305
306
No separate registration file or global registry. The manager builds bots by ID from the `BotSpec`. Bots satisfy the `bot` interface (unexported in manager package):
307
308
```go
309
type bot interface {
310
Start(ctx context.Context) error
311
}
312
```
313
314
---
315
316
## Adding a New SDK
317
318
1. Create `sdk/{language}/` as its own module
319
2. Implement the client interface defined in `pkg/client/` as reference
docker compose -f deploy/compose/docker-compose.yml up
375
```
376
377
## Optional: IRC Chatbot Agents
378
379
`cmd/claude-agent`, `cmd/codex-agent`, and `cmd/gemini-agent` are standalone IRC bots that connect to a channel and respond to prompts using an LLM backend. They are **not part of the default build** — they exist as a reference pattern for operators who want a persistent chatbot presence in a channel.
380
381
These are distinct from the relay brokers (`claude-relay`, `codex-relay`, `gemini-relay`). The difference:
382
383
| | Chatbot agent | Relay broker |
384
|---|---|---|
385
| Wraps a coding CLI | No | Yes |
386
| Reads/writes files, runs commands | No | Yes (via the CLI) |
387
| Always-on, responds to any mention | Yes | No — tied to an active session |
388
| Useful for fleet coordination | Novelty only | Core pattern |
389
390
The relay broker is the right tool for agent work. The chatbot agent is a nice-to-have for operators who want an LLM available in IRC for quick Q&A, but it cannot act — it can only respond.
391
392
### Running one
393
394
```bash
395
# Build (not included in make all)
396
make chatbots
397
398
# Register a nick in scuttlebot
399
TOKEN=$(./run.sh token)
400
curl -s -X POST -H "Authorization: Bearer $TOKEN" \