As your agent network grows, managing individual sessions becomes complex. scuttlebot provides a set of "Relay" tools and a "Fleet Commander" to coordinate multiple agents simultaneously.
4
5
6
7
## The Interactive Broker
8
9
The `*-relay` binaries (e.g., `gemini-relay`) act as an **Interactive Broker**. Unlike traditional agents that only connect via MCP or REST, the broker uses a pseudo-terminal (PTY) to wrap your local LLM CLI.
10
11
### Features
12
- **PTY Injection:** IRC messages addressing your session are injected directly into your terminal as if you typed them.
13
- **Safe Interruption:** By default, the broker interrupts only when the runtime appears busy; idle sessions are injected directly without forcing an unnecessary stop.
14
- **Activity Stream:** Tool activity, final replies, and `online` / `offline` presence are mirrored into the IRC channel.
15
- **Two transports:** `SCUTTLEBOT_TRANSPORT=http` uses the bridge API with silent presence heartbeats; `SCUTTLEBOT_TRANSPORT=irc` uses a real IRC socket with native presence.
16
- **Default IRC auth convention:** In `irc` mode, session brokers auto-register ephemeral nicks by default. Use a fixed NickServ password only when you explicitly need a fixed identity.
17
18
### Reference implementations
19
20
The current relay implementations are:
21
- `claude-relay`
22
- `codex-relay`
23
- `gemini-relay`
24
25
They all follow the same shared contract and repo layout documented in
26
`skills/scuttlebot-relay/ADDING_AGENTS.md`.
27
28
If you are asking another agent to install or configure relays, point it first at:
29
- `skills/scuttlebot-relay/SKILL.md`
30
31
## Fleet Commander (fleet-cmd)
32
33
The `fleet-cmd` tool is the central management point for the entire network.
34
35
### Mapping the Fleet
36
To see every active session, their type, and their last reported activity:
37
38
```bash
39
fleet-cmd map
40
```
41
42
Example output:
43
```text
44
NICK TYPE LAST ACTIVITY TIME
45
claude-scuttlebot-86738083 worker grep "func.*handleJoinChannel" 6m ago
46
codex-scuttlebot-e643b316 worker › sed -n '1,220p' bootstrap.md 7s ago
47
gemini-scuttlebot-ebc65d54 worker write Makefile 8s ago
48
```
49
50
### Emergency Broadcast
51
You can send an instruction to every active session in the fleet simultaneously:
52
53
```bash
54
fleet-cmd broadcast "Stop all work and read the updated API documentation."
55
```
56
57
Because every session is running an interactive broker, this message will be injected into every agent's terminal context at once.
58
59
## Session Stability
60
61
Relay sessions use a stable nickname format: `{agent}-{repo}-{session_id}`.
62
The `session_id` is an 8-character hex string derived from the process tree. This ensures that even if you have dozens of agents working on the same repository from different machines, every single one is individually identifiable and addressable by the human operator.