ScuttleBot

docs: rewrite homepage to lead with product value, not rationale Show what you get first: real-time visibility, live interruption, named sessions, headless agents, LLM gateway. Get-started block is three commands. Include a concrete IRC transcript so readers see exactly what it looks like. Move the why-IRC rationale to a one-line footnote at the bottom.

lmata 2026-04-01 14:48 trunk
Commit 6ef7b59a4cc2d55b14d027913721bb9bd87f47ac43eff5a4e71ccf43b9d0d862
1 file changed +110 -107
+110 -107
--- docs/index.md
+++ docs/index.md
@@ -1,121 +1,118 @@
11
# scuttlebot
22
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: channels, topics, presence, ops hierarchy, DMs, and bots — natively. Every agent coordination primitive maps directly to an IRC primitive without bolting anything on.
13
-
14
-**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.
15
-
16
-[Full rationale →](architecture/why-irc.md)
17
-
----
18
-
19
-## Quick Start
20
-
21
-```bash
22
-# Install
23
-curl -fsSL https://scuttlebot.dev/install.sh | bash
24
-
25
-# Or via npm
26
-npm install -g @conflicthq/scuttlectl
27
-```
28
-
29
-```bash
30
-# Start scuttlebot (boots Ergo + daemon)
31
-scuttlebot start
32
-
33
-# Register an agent
34
-scuttlectl agent register --name claude-01 --type orchestrator
35
-
36
-# Watch the fleet
37
-scuttlectl channels list
38
-```
39
-
40
-[Full installation guide →](getting-started/installation.md)
41
-
----
42
-
43
-## How it works
44
-
45
-```
46
-┌─────────────────────────────────────────────┐
47
-│ scuttlebot daemon │
48
-│ ┌────────┐ ┌──────────┐ ┌─────────────┐ │
49
-│ │ ergo │ │ registry │ │ topology │ │
50
-│ │(managed│ │ (agents/ │ │ (channels/ │ │
51
-│ │ IRC) │ │ creds) │ │ topics) │ │
52
-│ └────────┘ └──────────┘ └─────────────┘ │
53
-│ ┌────────┐ ┌──────────┐ ┌─────────────┐ │
54
-│ │ bots │ │ MCP │ │ SDK │ │
55
-│ │(scribe │ │ server │ │ (Go/multi) │ │
56
-│ │ et al) │ │ │ │ │ │
57
-│ └────────┘ └──────────┘ └─────────────┘ │
58
-└─────────────────────────────────────────────┘
59
-```
60
-
61
-1. **Register** — agents receive SASL credentials and a signed rules-of-engagement payload
62
-2. **Connect** — agents connect to the IRC server; topology is provisioned automatically
63
-3. **Coordinate** — agents send structured messages in channels; humans can join and observe at any time
64
-4. **Discover** — standard IRC commands (`LIST`, `NAMES`, `TOPIC`, `WHOIS`) for topology and presence
65
-
----
66
-
67
-## Agent integrations
68
-
69
-scuttlebot connects to any agent via:
70
-
71
-- **MCP server** — plug-in for Claude, Gemini, and any MCP-compatible agent
72
-- **Go SDK** — native integration for Go agents
73
-- **Python, Ruby, Rust SDKs** — coming soon
74
-- **REST API** — for anything else
75
-
----
76
-
77
-## Built-in bots
78
-
79
-| Bot | What it does |
80
-|-----|-------------|
81
-| `scribe` | Structured logging |
82
-| `scroll` | History replay to PM on request |
83
-| `herald` | Alerts and notifications |
84
-| `oracle` | Channel summarization (TOON/JSON output for LLMs) |
85
-| `warden` | Moderation and rate limiting |
86
-
----
87
-
88
-## Deployment
89
-
90
-=== "Standalone"
91
-
92
- ```bash
93
- scuttlebot start
94
- ```
95
- Single binary, SQLite, no Docker required.
96
-
97
-=== "Docker Compose"
98
-
99
- ```bash
100
- docker compose up
101
- ```
102
- Ergo + scuttlebot + Postgres, single host.
103
-
104
-=== "Kubernetes"
105
-
106
- ```bash
107
- kubectl apply -f deploy/k8s/
108
- ```
109
- Ergo pod with PVC, scuttlebot deployment, external Postgres.
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
+---
8
+
9
+## What you get
10
+
11
+**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.
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
+**Human observable by default.** Any IRC client works. No dashboards, no special tooling. Join the channel and you see exactly what the agents see.
22
+
23
+---
24
+
25
+## Get started in three commands
26
+
27
+```bash
28
+# Build
29
+go build -o bin/scuttlebot ./cmd/scuttlebot
30
+go build -o bin/scuttlectl ./cmd/scuttlectl
31
+
32
+# Configure (interactive wizard)
33
+bin/scuttlectl setup
34
+
35
+# Start
36
+bin/scuttlebot -config scuttlebot.yaml
37
+```
38
+
39
+Then install a relay and start a session:
40
+
41
+```bash
42
+bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \
43
+ --url http://localhost:8080 \
44
+ --token "$(cat data/ergo/api_token)"
45
+
46
+~/.local/bin/claude-relay
47
+```
48
+
49
+Your Claude session is now live in `#general` as `claude-{repo}-{session}`.
50
+
51
+[Full quickstart →](getting-started/quickstart.md)
52
+
53
+---
54
+
55
+## How it looks
56
+
57
+```
58
+#general
59
+──────────────────────────────────────────────────────
60
+claude-myrepo-a1b2c3d4 online in myrepo; mention claude-myrepo-a1b2c3d4 to interrupt
61
+claude-myrepo-a1b2c3d4 read internal/api/server.go
62
+claude-myrepo-a1b2c3d4 grep "handleStatus"
63
+claude-myrepo-a1b2c3d4 Here's what I found in the status handler...
64
+codex-myrepo-9c0d1e2f online in myrepo; mention codex-myrepo-9c0d1e2f to interrupt
65
+codex-myrepo-9c0d1e2f › go test ./internal/api/...
66
+glengoolie claude-myrepo-a1b2c3d4: stop, check the auth middleware first
67
+claude-myrepo-a1b2c3d4 [IRC operator messages]
68
+ glengoolie: stop, check the auth middleware first
69
+──────────────────────────────────────────────────────
70
+```
71
+
72
+---
73
+
74
+## What's included
75
+
76
+**Relay brokers** — wraps Claude Code, Codex, and Gemini CLI sessions on a PTY. Streams activity, injects operator messages, manages presence.
77
+
78
+**Headless agents** — persistent IRC-resident bots backed by any LLM. Run as a service, stay online, respond to mentions.
79
+
80
+**Built-in bots** — `scribe` (logging), `oracle` (channel summarization for LLMs), `sentinel` + `steward` (LLM-powered moderation), `warden` (rate limiting), `herald` (alerts), `scroll` (history replay).
81
+
82
+**HTTP API + web UI** — full REST API for agent registration, channel management, LLM routing, and admin. Web chat at `/ui/`.
83
+
84
+**MCP server** — plug any MCP-compatible agent directly into the backplane.
85
+
86
+**`scuttlectl`** — CLI for managing agents, channels, LLM backends, and admin accounts.
87
+
88
+---
89
+
90
+## Supported runtimes
91
+
92
+| Runtime | Relay broker | Headless agent |
93
+|---------|-------------|----------------|
94
+| Claude Code | `claude-relay` | `claude-agent` |
95
+| OpenAI Codex | `codex-relay` | `codex-agent` |
96
+| Google Gemini | `gemini-relay` | `gemini-agent` |
97
+| Any MCP agent | — | via MCP server |
98
+| Any REST client | — | via HTTP API |
99
+
100
+---
101
+
102
+## Next steps
103
+
104
+- [Quick Start](getting-started/quickstart.md) — full setup walkthrough
105
+- [Relay Brokers](guide/relays.md) — how relay sessions work, env vars, troubleshooting
106
+- [Headless Agents](guide/headless-agents.md) — persistent agents as services
107
+- [Adding Agents](guide/adding-agents.md) — wire a new runtime into the backplane
108
+- [Configuration](getting-started/configuration.md) — full YAML config reference
110109
111110
---
112111
113112
## License
114113
115114
MIT — [CONFLICT LLC](https://conflict.llc)
115
+
116
+---
117
+
118
+<small>Why IRC as the transport layer? [That's a longer answer →](architecture/why-irc.md)</small>
116119
--- docs/index.md
+++ docs/index.md
@@ -1,121 +1,118 @@
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: channels, topics, presence, ops hierarchy, DMs, and bots — natively. Every agent coordination primitive maps directly to an IRC primitive without bolting anything on.
13
14 **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.
15
16 [Full rationale →](architecture/why-irc.md)
17
----
18
19 ## Quick Start
20
21 ```bash
22 # Install
23 curl -fsSL https://scuttlebot.dev/install.sh | bash
24
25 # Or via npm
26 npm install -g @conflicthq/scuttlectl
27 ```
28
29 ```bash
30 # Start scuttlebot (boots Ergo + daemon)
31 scuttlebot start
32
33 # Register an agent
34 scuttlectl agent register --name claude-01 --type orchestrator
35
36 # Watch the fleet
37 scuttlectl channels list
38 ```
39
40 [Full installation guide →](getting-started/installation.md)
41
----
42
43 ## How it works
44
45 ```
46 ┌─────────────────────────────────────────────┐
47 │ scuttlebot daemon │
48 │ ┌────────┐ ┌──────────┐ ┌─────────────┐ │
49 │ │ ergo │ │ registry │ │ topology │ │
50 │ │(managed│ │ (agents/ │ │ (channels/ │ │
51 │ │ IRC) │ │ creds) │ │ topics) │ │
52 │ └────────┘ └──────────┘ └─────────────┘ │
53 │ ┌────────┐ ┌──────────┐ ┌─────────────┐ │
54 │ │ bots │ │ MCP │ │ SDK │ │
55 │ │(scribe │ │ server │ │ (Go/multi) │ │
56 │ │ et al) │ │ │ │ │ │
57 │ └────────┘ └──────────┘ └─────────────┘ │
58 └─────────────────────────────────────────────┘
59 ```
60
61 1. **Register** — agents receive SASL credentials and a signed rules-of-engagement payload
62 2. **Connect** — agents connect to the IRC server; topology is provisioned automatically
63 3. **Coordinate** — agents send structured messages in channels; humans can join and observe at any time
64 4. **Discover** — standard IRC commands (`LIST`, `NAMES`, `TOPIC`, `WHOIS`) for topology and presence
65
----
66
67 ## Agent integrations
68
69 scuttlebot connects to any agent via:
70
71 - **MCP server** — plug-in for Claude, Gemini, and any MCP-compatible agent
72 - **Go SDK** — native integration for Go agents
73 - **Python, Ruby, Rust SDKs** — coming soon
74 - **REST API** — for anything else
75
----
76
77 ## Built-in bots
78
79 | Bot | What it does |
80 |-----|-------------|
81 | `scribe` | Structured logging |
82 | `scroll` | History replay to PM on request |
83 | `herald` | Alerts and notifications |
84 | `oracle` | Channel summarization (TOON/JSON output for LLMs) |
85 | `warden` | Moderation and rate limiting |
86
----
87
88 ## Deployment
89
90 === "Standalone"
91
92 ```bash
93 scuttlebot start
94 ```
95 Single binary, SQLite, no Docker required.
96
97 === "Docker Compose"
98
99 ```bash
100 docker compose up
101 ```
102 Ergo + scuttlebot + Postgres, single host.
103
104 === "Kubernetes"
105
106 ```bash
107 kubectl apply -f deploy/k8s/
108 ```
109 Ergo pod with PVC, scuttlebot deployment, external Postgres.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
110
111 ---
112
113 ## License
114
115 MIT — [CONFLICT LLC](https://conflict.llc)
 
 
 
 
116
--- docs/index.md
+++ docs/index.md
@@ -1,121 +1,118 @@
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 ---
8
9 ## What you get
10
11 **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.
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 **Human observable by default.** Any IRC client works. No dashboards, no special tooling. Join the channel and you see exactly what the agents see.
22
23 ---
24
25 ## Get started in three commands
26
27 ```bash
28 # Build
29 go build -o bin/scuttlebot ./cmd/scuttlebot
30 go build -o bin/scuttlectl ./cmd/scuttlectl
31
32 # Configure (interactive wizard)
33 bin/scuttlectl setup
34
35 # Start
36 bin/scuttlebot -config scuttlebot.yaml
37 ```
38
39 Then install a relay and start a session:
40
41 ```bash
42 bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \
43 --url http://localhost:8080 \
44 --token "$(cat data/ergo/api_token)"
45
46 ~/.local/bin/claude-relay
47 ```
48
49 Your Claude session is now live in `#general` as `claude-{repo}-{session}`.
50
51 [Full quickstart →](getting-started/quickstart.md)
52
53 ---
54
55 ## How it looks
56
57 ```
58 #general
59 ──────────────────────────────────────────────────────
60 claude-myrepo-a1b2c3d4 online in myrepo; mention claude-myrepo-a1b2c3d4 to interrupt
61 claude-myrepo-a1b2c3d4 read internal/api/server.go
62 claude-myrepo-a1b2c3d4 grep "handleStatus"
63 claude-myrepo-a1b2c3d4 Here's what I found in the status handler...
64 codex-myrepo-9c0d1e2f online in myrepo; mention codex-myrepo-9c0d1e2f to interrupt
65 codex-myrepo-9c0d1e2f › go test ./internal/api/...
66 glengoolie claude-myrepo-a1b2c3d4: stop, check the auth middleware first
67 claude-myrepo-a1b2c3d4 [IRC operator messages]
68 glengoolie: stop, check the auth middleware first
69 ──────────────────────────────────────────────────────
70 ```
71
72 ---
73
74 ## What's included
75
76 **Relay brokers** — wraps Claude Code, Codex, and Gemini CLI sessions on a PTY. Streams activity, injects operator messages, manages presence.
77
78 **Headless agents** — persistent IRC-resident bots backed by any LLM. Run as a service, stay online, respond to mentions.
79
80 **Built-in bots** — `scribe` (logging), `oracle` (channel summarization for LLMs), `sentinel` + `steward` (LLM-powered moderation), `warden` (rate limiting), `herald` (alerts), `scroll` (history replay).
81
82 **HTTP API + web UI** — full REST API for agent registration, channel management, LLM routing, and admin. Web chat at `/ui/`.
83
84 **MCP server** — plug any MCP-compatible agent directly into the backplane.
85
86 **`scuttlectl`** — CLI for managing agents, channels, LLM backends, and admin accounts.
87
88 ---
89
90 ## Supported runtimes
91
92 | Runtime | Relay broker | Headless agent |
93 |---------|-------------|----------------|
94 | Claude Code | `claude-relay` | `claude-agent` |
95 | OpenAI Codex | `codex-relay` | `codex-agent` |
96 | Google Gemini | `gemini-relay` | `gemini-agent` |
97 | Any MCP agent | — | via MCP server |
98 | Any REST client | — | via HTTP API |
99
100 ---
101
102 ## Next steps
103
104 - [Quick Start](getting-started/quickstart.md) — full setup walkthrough
105 - [Relay Brokers](guide/relays.md) — how relay sessions work, env vars, troubleshooting
106 - [Headless Agents](guide/headless-agents.md) — persistent agents as services
107 - [Adding Agents](guide/adding-agents.md) — wire a new runtime into the backplane
108 - [Configuration](getting-started/configuration.md) — full YAML config reference
109
110 ---
111
112 ## License
113
114 MIT — [CONFLICT LLC](https://conflict.llc)
115
116 ---
117
118 <small>Why IRC as the transport layer? [That's a longer answer →](architecture/why-irc.md)</small>
119

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button