ScuttleBot

Document shared relay skill in public docs

lmata 2026-04-01 14:46 trunk

Commit 66a19022092b1abc032ee053af24a545fa36f729bdad97def3d9903e5a59f3a4

Parent 1b994dac5b953cc…

3 files changed +19 -5 +17 +17 -2

~ README.md ~ docs/getting-started/installation.md ~ docs/guide/fleet-management.md

M README.md

+19 -5

		--- README.md
		+++ README.md
		@@ -55,17 +55,31 @@
55	55
56	56	---
57	57
58	58	## Fleet Management & Relays
59	59
60		-scuttlebot provides an Interactive Broker for local LLM terminal sessions (Claude Code, Gemini, Codex).
	60	+scuttlebot provides an Interactive Broker for local LLM terminal sessions
	61	+(Claude Code, Gemini CLI, Codex).
61	62
62	63	By running your agent through a scuttlebot relay, you get:
63		-- Real-time Observability: Every tool call is automatically posted to an IRC channel.
64		-- Human-in-the-loop Control: Operators can mention the agent's nick in IRC to inject instructions directly into its terminal context.
65		-- PTY Wrapper: The relay uses a real pseudo-terminal to wrap the agent, enabling seamless interaction and interrupts.
66		-- Fleet Commander: Use `fleet-cmd` to map every active session across your network and broadcast emergency instructions to the entire fleet at once.
	64	+- Real-time Observability: Tool activity, assistant replies, and `online` / `offline`
	65	+ presence are mirrored into IRC.
	66	+- Human-in-the-loop Control: Operators can mention the session nick in IRC to inject
	67	+ instructions directly into the live terminal context.
	68	+- Two transport modes: Use the HTTP bridge path or a real IRC socket. In IRC mode,
	69	+ session brokers auto-register ephemeral nicks by default and show up as real agents.
	70	+- PTY Wrapper: The relay uses a real pseudo-terminal to wrap the agent, enabling
	71	+ seamless interaction and safe interrupts.
	72	+- Fleet Commander: Use `fleet-cmd` to map every active session across your network
	73	+ and broadcast emergency instructions to the entire fleet at once.
	74	+
	75	+Detailed runtime primers live under:
	76	+- `skills/scuttlebot-relay/SKILL.md` for the shared install/config skill
	77	+- `skills/scuttlebot-relay/` for Claude
	78	+- `skills/openai-relay/` for Codex
	79	+- `skills/gemini-relay/` for Gemini
	80	+- `skills/scuttlebot-relay/ADDING_AGENTS.md` for the shared relay contract
67	81
68	82	---
69	83
70	84	## How it works
71	85
72	86

	--- README.md
	+++ README.md
	@@ -55,17 +55,31 @@
55
56	---
57
58	## Fleet Management & Relays
59
60	scuttlebot provides an Interactive Broker for local LLM terminal sessions (Claude Code, Gemini, Codex).

61
62	By running your agent through a scuttlebot relay, you get:
63	- Real-time Observability: Every tool call is automatically posted to an IRC channel.
64	- Human-in-the-loop Control: Operators can mention the agent's nick in IRC to inject instructions directly into its terminal context.
65	- PTY Wrapper: The relay uses a real pseudo-terminal to wrap the agent, enabling seamless interaction and interrupts.
66	- Fleet Commander: Use `fleet-cmd` to map every active session across your network and broadcast emergency instructions to the entire fleet at once.













67
68	---
69
70	## How it works
71
72

	--- README.md
	+++ README.md
	@@ -55,17 +55,31 @@
55
56	---
57
58	## Fleet Management & Relays
59
60	scuttlebot provides an Interactive Broker for local LLM terminal sessions
61	(Claude Code, Gemini CLI, Codex).
62
63	By running your agent through a scuttlebot relay, you get:
64	- Real-time Observability: Tool activity, assistant replies, and `online` / `offline`
65	presence are mirrored into IRC.
66	- Human-in-the-loop Control: Operators can mention the session nick in IRC to inject
67	instructions directly into the live terminal context.
68	- Two transport modes: Use the HTTP bridge path or a real IRC socket. In IRC mode,
69	session brokers auto-register ephemeral nicks by default and show up as real agents.
70	- PTY Wrapper: The relay uses a real pseudo-terminal to wrap the agent, enabling
71	seamless interaction and safe interrupts.
72	- Fleet Commander: Use `fleet-cmd` to map every active session across your network
73	and broadcast emergency instructions to the entire fleet at once.
74
75	Detailed runtime primers live under:
76	- `skills/scuttlebot-relay/SKILL.md` for the shared install/config skill
77	- `skills/scuttlebot-relay/` for Claude
78	- `skills/openai-relay/` for Codex
79	- `skills/gemini-relay/` for Gemini
80	- `skills/scuttlebot-relay/ADDING_AGENTS.md` for the shared relay contract
81
82	---
83
84	## How it works
85
86

M docs/getting-started/installation.md

+17

		--- docs/getting-started/installation.md
		+++ docs/getting-started/installation.md
		@@ -30,10 +30,17 @@
30	30
31	31	## Agent Relay Installation
32	32
33	33	If you are running local LLM terminal sessions (Claude Code, Gemini CLI, etc.) and want to wire them into scuttlebot, use the tracked relay installers.
34	34
	35	+By default, the relay installers configure the interactive broker pattern:
	36	+- local CLI wrapped in a PTY broker
	37	+- IRC-visible `online` / `offline` presence
	38	+- live operator message injection from IRC
	39	+- default IRC auth via ephemeral auto-registration when transport is `irc`
	40	+- fixed NickServ passwords only when you explicitly opt into `--irc-pass`
	41	+
35	42	### Claude Code Relay
36	43	```bash
37	44	SCUTTLEBOT_URL=http://localhost:8080 \
38	45	SCUTTLEBOT_TOKEN="your-token" \
39	46	SCUTTLEBOT_CHANNEL=general \
		@@ -55,5 +62,15 @@
55	62	SCUTTLEBOT_CHANNEL=general \
56	63	make install-codex-relay
57	64	```
58	65
59	66	These installers set up the interactive broker, PTY wrappers, and tool-use hooks automatically.
	67	+Installed files under `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.local/bin/`, and
	68	+`~/.config/` are generated copies. The repo docs remain the source of truth.
	69	+
	70	+For agent-driven install/config work across runtimes, start with the shared relay skill:
	71	+- `skills/scuttlebot-relay/SKILL.md`
	72	+
	73	+For detailed runtime-specific setup and fleet rollout:
	74	+- Claude: `skills/scuttlebot-relay/install.md`
	75	+- Codex: `skills/openai-relay/install.md`
	76	+- Gemini: `skills/gemini-relay/install.md`
60	77

	--- docs/getting-started/installation.md
	+++ docs/getting-started/installation.md
	@@ -30,10 +30,17 @@
30
31	## Agent Relay Installation
32
33	If you are running local LLM terminal sessions (Claude Code, Gemini CLI, etc.) and want to wire them into scuttlebot, use the tracked relay installers.
34







35	### Claude Code Relay
36	```bash
37	SCUTTLEBOT_URL=http://localhost:8080 \
38	SCUTTLEBOT_TOKEN="your-token" \
39	SCUTTLEBOT_CHANNEL=general \
	@@ -55,5 +62,15 @@
55	SCUTTLEBOT_CHANNEL=general \
56	make install-codex-relay
57	```
58
59	These installers set up the interactive broker, PTY wrappers, and tool-use hooks automatically.










60

	--- docs/getting-started/installation.md
	+++ docs/getting-started/installation.md
	@@ -30,10 +30,17 @@
30
31	## Agent Relay Installation
32
33	If you are running local LLM terminal sessions (Claude Code, Gemini CLI, etc.) and want to wire them into scuttlebot, use the tracked relay installers.
34
35	By default, the relay installers configure the interactive broker pattern:
36	- local CLI wrapped in a PTY broker
37	- IRC-visible `online` / `offline` presence
38	- live operator message injection from IRC
39	- default IRC auth via ephemeral auto-registration when transport is `irc`
40	- fixed NickServ passwords only when you explicitly opt into `--irc-pass`
41
42	### Claude Code Relay
43	```bash
44	SCUTTLEBOT_URL=http://localhost:8080 \
45	SCUTTLEBOT_TOKEN="your-token" \
46	SCUTTLEBOT_CHANNEL=general \
	@@ -55,5 +62,15 @@
62	SCUTTLEBOT_CHANNEL=general \
63	make install-codex-relay
64	```
65
66	These installers set up the interactive broker, PTY wrappers, and tool-use hooks automatically.
67	Installed files under `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.local/bin/`, and
68	`~/.config/` are generated copies. The repo docs remain the source of truth.
69
70	For agent-driven install/config work across runtimes, start with the shared relay skill:
71	- `skills/scuttlebot-relay/SKILL.md`
72
73	For detailed runtime-specific setup and fleet rollout:
74	- Claude: `skills/scuttlebot-relay/install.md`
75	- Codex: `skills/openai-relay/install.md`
76	- Gemini: `skills/gemini-relay/install.md`
77

M docs/guide/fleet-management.md

+17 -2

		--- docs/guide/fleet-management.md
		+++ docs/guide/fleet-management.md
		@@ -6,12 +6,27 @@
6	6
7	7	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.
8	8
9	9	### Features
10	10	- PTY Injection: IRC messages addressing your session are injected directly into your terminal as if you typed them.
11		-- Immediate Interruption: By default, the broker sends a `Ctrl+C` interrupt followed by the IRC instruction, ensuring the agent stops and listens immediately.
12		-- Activity Stream: Every tool used by the agent is posted to the IRC channel as a status line.
	11	+- Safe Interruption: By default, the broker interrupts only when the runtime appears busy; idle sessions are injected directly without forcing an unnecessary stop.
	12	+- Activity Stream: Tool activity, final replies, and `online` / `offline` presence are mirrored into the IRC channel.
	13	+- Two transports: `SCUTTLEBOT_TRANSPORT=http` uses the bridge API with silent presence heartbeats; `SCUTTLEBOT_TRANSPORT=irc` uses a real IRC socket with native presence.
	14	+- 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.
	15	+
	16	+### Reference implementations
	17	+
	18	+The current relay implementations are:
	19	+- `claude-relay`
	20	+- `codex-relay`
	21	+- `gemini-relay`
	22	+
	23	+They all follow the same shared contract and repo layout documented in
	24	+`skills/scuttlebot-relay/ADDING_AGENTS.md`.
	25	+
	26	+If you are asking another agent to install or configure relays, point it first at:
	27	+- `skills/scuttlebot-relay/SKILL.md`
13	28
14	29	## Fleet Commander (fleet-cmd)
15	30
16	31	The `fleet-cmd` tool is the central management point for the entire network.
17	32
18	33

	--- docs/guide/fleet-management.md
	+++ docs/guide/fleet-management.md
	@@ -6,12 +6,27 @@
6
7	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.
8
9	### Features
10	- PTY Injection: IRC messages addressing your session are injected directly into your terminal as if you typed them.
11	- Immediate Interruption: By default, the broker sends a `Ctrl+C` interrupt followed by the IRC instruction, ensuring the agent stops and listens immediately.
12	- Activity Stream: Every tool used by the agent is posted to the IRC channel as a status line.















13
14	## Fleet Commander (fleet-cmd)
15
16	The `fleet-cmd` tool is the central management point for the entire network.
17
18

	--- docs/guide/fleet-management.md
	+++ docs/guide/fleet-management.md
	@@ -6,12 +6,27 @@
6
7	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.
8
9	### Features
10	- PTY Injection: IRC messages addressing your session are injected directly into your terminal as if you typed them.
11	- Safe Interruption: By default, the broker interrupts only when the runtime appears busy; idle sessions are injected directly without forcing an unnecessary stop.
12	- Activity Stream: Tool activity, final replies, and `online` / `offline` presence are mirrored into the IRC channel.
13	- Two transports: `SCUTTLEBOT_TRANSPORT=http` uses the bridge API with silent presence heartbeats; `SCUTTLEBOT_TRANSPORT=irc` uses a real IRC socket with native presence.
14	- 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.
15
16	### Reference implementations
17
18	The current relay implementations are:
19	- `claude-relay`
20	- `codex-relay`
21	- `gemini-relay`
22
23	They all follow the same shared contract and repo layout documented in
24	`skills/scuttlebot-relay/ADDING_AGENTS.md`.
25
26	If you are asking another agent to install or configure relays, point it first at:
27	- `skills/scuttlebot-relay/SKILL.md`
28
29	## Fleet Commander (fleet-cmd)
30
31	The `fleet-cmd` tool is the central management point for the entire network.
32
33

ScuttleBot

Keyboard Shortcuts