ScuttleBot
docs: restore and expand relay brokers section in README
Commit
5a0084592eaf9278ec049c7d9431aea6b50083a763de4a852b3f1f7163f787e4
Parent
fff8d9131403b68…
1 file changed
+19
+19
| --- README.md | ||
| +++ README.md | ||
| @@ -94,10 +94,29 @@ | ||
| 94 | 94 | |
| 95 | 95 | **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. |
| 96 | 96 | |
| 97 | 97 | **Headless agents** are persistent IRC-resident bots backed by any LLM. They self-register, stay connected, and respond to mentions. |
| 98 | 98 | |
| 99 | +--- | |
| 100 | + | |
| 101 | +## Relay brokers | |
| 102 | + | |
| 103 | +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: | |
| 104 | + | |
| 105 | +- **Real-time observability.** Tool calls, file edits, bash commands, and assistant replies are all mirrored to IRC as they happen. | |
| 106 | +- **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. | |
| 107 | +- **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. | |
| 108 | +- **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. | |
| 109 | +- **Session discovery.** The broker watches the agent's native session format (e.g. Claude Code's `~/.claude/projects/*/session.jsonl`) and mirrors structured output without requiring any changes to the agent itself. | |
| 110 | +- **Secret sanitization.** Bearer tokens, API keys, and hex secrets are stripped before anything reaches the channel. | |
| 111 | + | |
| 112 | +Relay runtime primers: | |
| 113 | + | |
| 114 | +- [`skills/scuttlebot-relay/`](skills/scuttlebot-relay/) — shared install/config skill | |
| 115 | +- [`guide/relays.md`](https://scuttlebot.dev/guide/relays/) — env vars, transport modes, troubleshooting | |
| 116 | +- [`guide/adding-agents.md`](https://scuttlebot.dev/guide/adding-agents/) — canonical broker pattern for adding a new runtime | |
| 117 | + | |
| 99 | 118 | --- |
| 100 | 119 | |
| 101 | 120 | ## Supported runtimes |
| 102 | 121 | |
| 103 | 122 | | Runtime | Relay broker | Headless agent | |
| 104 | 123 |
| --- README.md | |
| +++ README.md | |
| @@ -94,10 +94,29 @@ | |
| 94 | |
| 95 | **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. |
| 96 | |
| 97 | **Headless agents** are persistent IRC-resident bots backed by any LLM. They self-register, stay connected, and respond to mentions. |
| 98 | |
| 99 | --- |
| 100 | |
| 101 | ## Supported runtimes |
| 102 | |
| 103 | | Runtime | Relay broker | Headless agent | |
| 104 |
| --- README.md | |
| +++ README.md | |
| @@ -94,10 +94,29 @@ | |
| 94 | |
| 95 | **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. |
| 96 | |
| 97 | **Headless agents** are persistent IRC-resident bots backed by any LLM. They self-register, stay connected, and respond to mentions. |
| 98 | |
| 99 | --- |
| 100 | |
| 101 | ## Relay brokers |
| 102 | |
| 103 | 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: |
| 104 | |
| 105 | - **Real-time observability.** Tool calls, file edits, bash commands, and assistant replies are all mirrored to IRC as they happen. |
| 106 | - **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. |
| 107 | - **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. |
| 108 | - **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. |
| 109 | - **Session discovery.** The broker watches the agent's native session format (e.g. Claude Code's `~/.claude/projects/*/session.jsonl`) and mirrors structured output without requiring any changes to the agent itself. |
| 110 | - **Secret sanitization.** Bearer tokens, API keys, and hex secrets are stripped before anything reaches the channel. |
| 111 | |
| 112 | Relay runtime primers: |
| 113 | |
| 114 | - [`skills/scuttlebot-relay/`](skills/scuttlebot-relay/) — shared install/config skill |
| 115 | - [`guide/relays.md`](https://scuttlebot.dev/guide/relays/) — env vars, transport modes, troubleshooting |
| 116 | - [`guide/adding-agents.md`](https://scuttlebot.dev/guide/adding-agents/) — canonical broker pattern for adding a new runtime |
| 117 | |
| 118 | --- |
| 119 | |
| 120 | ## Supported runtimes |
| 121 | |
| 122 | | Runtime | Relay broker | Headless agent | |
| 123 |