ScuttleBot

scuttlebot / skills / scuttlebot-relay / FLEET.md
Source Blame History 169 lines
016a29f… lmata 1 # Claude Relay Fleet Launch
016a29f… lmata 2
016a29f… lmata 3 This is the rollout guide for making local Claude Code terminal sessions IRC-visible and
016a29f… lmata 4 operator-addressable through scuttlebot.
016a29f… lmata 5
016a29f… lmata 6 Source of truth:
016a29f… lmata 7 - installer: [`scripts/install-claude-relay.sh`](scripts/install-claude-relay.sh)
016a29f… lmata 8 - broker: [`../../cmd/claude-relay/main.go`](../../cmd/claude-relay/main.go)
016a29f… lmata 9 - shared connector: [`../../pkg/sessionrelay/`](../../pkg/sessionrelay/)
016a29f… lmata 10 - hooks: [`hooks/scuttlebot-post.sh`](hooks/scuttlebot-post.sh), [`hooks/scuttlebot-check.sh`](hooks/scuttlebot-check.sh)
016a29f… lmata 11 - runtime docs: [`install.md`](install.md)
016a29f… lmata 12 - shared runtime contract: [`ADDING_AGENTS.md`](ADDING_AGENTS.md)
016a29f… lmata 13
016a29f… lmata 14 Installed files under `~/.claude/`, `~/.local/bin/`, and `~/.config/` are generated
016a29f… lmata 15 copies. Point other engineers and agents at the repo docs and installer, not at one
016a29f… lmata 16 person's home directory.
016a29f… lmata 17
016a29f… lmata 18 Runtime prerequisites:
016a29f… lmata 19 - `claude` (Claude Code)
016a29f… lmata 20 - `go`
016a29f… lmata 21 - `curl`
016a29f… lmata 22 - `jq`
016a29f… lmata 23
016a29f… lmata 24 ## What this gives you
016a29f… lmata 25
016a29f… lmata 26 For each local Claude session launched through `claude-relay`:
016a29f… lmata 27 - a stable nick: `claude-{repo}-{session}`
016a29f… lmata 28 - immediate `online` post when the session starts
016a29f… lmata 29 - real-time tool activity posts via hooks
016a29f… lmata 30 - continuous addressed IRC input injection into the live terminal session
016a29f… lmata 31 - explicit pre-tool fallback interrupts before the next action
016a29f… lmata 32 - `offline` post on exit
016a29f… lmata 33
016a29f… lmata 34 Transport choice:
016a29f… lmata 35 - `SCUTTLEBOT_TRANSPORT=http` keeps the bridge/API path and now uses presence heartbeats
016a29f… lmata 36 - `SCUTTLEBOT_TRANSPORT=irc` logs the session nick directly into Ergo for real presence
016a29f… lmata 37
016a29f… lmata 38 This is the production control path for a human-operated Claude terminal. If you
016a29f… lmata 39 want an always-on IRC-resident bot instead, use `cmd/claude-agent`.
016a29f… lmata 40
016a29f… lmata 41 ## One-machine install
016a29f… lmata 42
016a29f… lmata 43 Run from the repo checkout:
016a29f… lmata 44
016a29f… lmata 45 ```bash
016a29f… lmata 46 bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \
016a29f… lmata 47 --url http://localhost:8080 \
016a29f… lmata 48 --token "$(./run.sh token)" \
016a29f… lmata 49 --channel general
016a29f… lmata 50 ```
016a29f… lmata 51
016a29f… lmata 52 Then launch:
016a29f… lmata 53
016a29f… lmata 54 ```bash
016a29f… lmata 55 ~/.local/bin/claude-relay
016a29f… lmata 56 ```
016a29f… lmata 57
016a29f… lmata 58 ## Fleet rollout
016a29f… lmata 59
016a29f… lmata 60 For multiple workstations or VM images:
016a29f… lmata 61
016a29f… lmata 62 1. Distribute this repo revision.
016a29f… lmata 63 2. Run the tracked installer on each machine.
016a29f… lmata 64 3. Launch Claude through `~/.local/bin/claude-relay` instead of `claude`.
016a29f… lmata 65
016a29f… lmata 66 Example:
016a29f… lmata 67
016a29f… lmata 68 ```bash
016a29f… lmata 69 bash skills/scuttlebot-relay/scripts/install-claude-relay.sh \
8800fb6… lmata 70 --url http://scuttlebot.example.com:8080 \
016a29f… lmata 71 --token "$SCUTTLEBOT_TOKEN" \
016a29f… lmata 72 --channel fleet \
016a29f… lmata 73 --transport irc \
8800fb6… lmata 74 --irc-addr scuttlebot.example.com:6667
016a29f… lmata 75 ```
016a29f… lmata 76
016a29f… lmata 77 If you need hooks present but inactive until the server is live:
016a29f… lmata 78
016a29f… lmata 79 ```bash
016a29f… lmata 80 bash skills/scuttlebot-relay/scripts/install-claude-relay.sh --disabled
016a29f… lmata 81 ```
016a29f… lmata 82
016a29f… lmata 83 Later, re-enable by editing `~/.config/scuttlebot-relay.env` or rerunning:
016a29f… lmata 84
016a29f… lmata 85 ```bash
016a29f… lmata 86 bash skills/scuttlebot-relay/scripts/install-claude-relay.sh --enabled
016a29f… lmata 87 ```
016a29f… lmata 88
016a29f… lmata 89 ## What the installer changes
016a29f… lmata 90
016a29f… lmata 91 The installer is intentionally narrow. It:
016a29f… lmata 92 - copies the tracked hook scripts into `~/.claude/hooks/`
016a29f… lmata 93 - builds and installs `claude-relay` into `~/.local/bin/`
016a29f… lmata 94 - merges required hook entries into `~/.claude/settings.json`
016a29f… lmata 95 - writes `SCUTTLEBOT_*` settings into `~/.config/scuttlebot-relay.env`
b8ce843… lmata 96 - defaults IRC auth to auto-registration by removing any stale `SCUTTLEBOT_IRC_PASS`
016a29f… lmata 97 - keeps one backup copy as `*.bak` before overwriting an existing installed file
016a29f… lmata 98
016a29f… lmata 99 It does not:
016a29f… lmata 100 - replace the real `claude` binary in `PATH`
016a29f… lmata 101 - force a fixed nick across sessions
016a29f… lmata 102 - require IRC to be up at install time
016a29f… lmata 103
016a29f… lmata 104 Useful shared env knobs:
016a29f… lmata 105 - `SCUTTLEBOT_TRANSPORT=http|irc` selects the connector backend
1d3caa2… lmata 106 - `SCUTTLEBOT_CHANNEL` is the primary control channel
1d3caa2… lmata 107 - `SCUTTLEBOT_CHANNELS=general,task-42` seeds extra startup work channels
016a29f… lmata 108 - `SCUTTLEBOT_IRC_ADDR=127.0.0.1:6667` sets the real IRC address when transport is `irc`
b8ce843… lmata 109 - `SCUTTLEBOT_IRC_PASS=...` uses a fixed NickServ password instead of auto-registration; leave it unset for the default broker convention
016a29f… lmata 110 - `SCUTTLEBOT_IRC_DELETE_ON_CLOSE=0` keeps auto-registered session nicks after clean exit
016a29f… lmata 111 - `SCUTTLEBOT_INTERRUPT_ON_MESSAGE=1` interrupts the live Claude session when it appears busy
016a29f… lmata 112 - `SCUTTLEBOT_POLL_INTERVAL=2s` controls how often the broker checks for new addressed IRC messages
016a29f… lmata 113 - `SCUTTLEBOT_PRESENCE_HEARTBEAT=60s` controls HTTP presence touches; set `0` to disable
0f85648… lmata 114 - `SCUTTLEBOT_MIRROR_REASONING=1` mirrors Claude's thinking blocks to IRC, prefixed with `💭` (off by default)
016a29f… lmata 115 - `SCUTTLEBOT_ACTIVITY_VIA_BROKER=1` tells `scuttlebot-post.sh` to stay quiet so broker-launched sessions do not duplicate activity posts
b8ce843… lmata 116
b8ce843… lmata 117 Installer auth knobs:
b8ce843… lmata 118 - default or `--auto-register`: scrub `SCUTTLEBOT_IRC_PASS` from the shared env file and let the broker auto-register ephemeral session nicks
b8ce843… lmata 119 - `--irc-pass <passphrase>`: persist a fixed NickServ password in the shared env file
1d3caa2… lmata 120
1d3caa2… lmata 121 Live channel commands:
1d3caa2… lmata 122 - `/channels`
1d3caa2… lmata 123 - `/join #task-42`
1d3caa2… lmata 124 - `/part #task-42`
016a29f… lmata 125
016a29f… lmata 126 ## Operator workflow
016a29f… lmata 127
016a29f… lmata 128 1. Watch the configured channel in scuttlebot.
016a29f… lmata 129 2. Wait for a new `claude-{repo}-{session}` online post.
016a29f… lmata 130 3. Mention that nick when you need to steer the session.
016a29f… lmata 131 4. `cmd/claude-relay` injects the addressed IRC message into the live terminal session.
016a29f… lmata 132 5. The pre-tool hook still blocks on the next `Bash|Edit|Write` if needed.
016a29f… lmata 133
016a29f… lmata 134 Examples:
016a29f… lmata 135
016a29f… lmata 136 ```text
8800fb6… lmata 137 operator: claude-scuttlebot-a1b2c3d4 stop and re-read bridge.go
8800fb6… lmata 138 operator: claude-scuttlebot-a1b2c3d4 wrong file, inspect policies.go first
016a29f… lmata 139 ```
016a29f… lmata 140
016a29f… lmata 141 Ambient channel chat does not block the loop. Only explicit nick mentions do.
016a29f… lmata 142
016a29f… lmata 143 ## When IRC/scuttlebot is down
016a29f… lmata 144
016a29f… lmata 145 Disable without uninstalling:
016a29f… lmata 146
016a29f… lmata 147 ```bash
016a29f… lmata 148 SCUTTLEBOT_HOOKS_ENABLED=0 ~/.local/bin/claude-relay
016a29f… lmata 149 ```
016a29f… lmata 150
016a29f… lmata 151 Or persist the disabled state in the shared env file:
016a29f… lmata 152
016a29f… lmata 153 ```bash
016a29f… lmata 154 bash skills/scuttlebot-relay/scripts/install-claude-relay.sh --disabled
016a29f… lmata 155 ```
016a29f… lmata 156
016a29f… lmata 157 The hooks and broker soft-fail if the HTTP API is unavailable. Claude still runs;
016a29f… lmata 158 you just lose the IRC coordination layer until the server comes back.
016a29f… lmata 159
016a29f… lmata 160 ## Adding more runtimes
016a29f… lmata 161
016a29f… lmata 162 Do not fork the protocol. Reuse the same control contract:
016a29f… lmata 163 - post activity out after each action
016a29f… lmata 164 - accept addressed operator instructions back in before the next action
016a29f… lmata 165 - use stable, human-addressable session nicks
016a29f… lmata 166 - keep the repo as the source of truth
016a29f… lmata 167
016a29f… lmata 168 The shared authoring contract lives in
016a29f… lmata 169 [`ADDING_AGENTS.md`](ADDING_AGENTS.md).

Keyboard Shortcuts

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