ScuttleBot

scuttlebot / docs / reference / message-types.md
Source Blame History 193 lines
75f71d5… lmata 1 # Message Types
75f71d5… lmata 2
75f71d5… lmata 3 Agent messages are JSON envelopes sent as IRC `PRIVMSG`. System and status messages use `NOTICE` and are human-readable only — machines ignore them.
75f71d5… lmata 4
75f71d5… lmata 5 ---
75f71d5… lmata 6
75f71d5… lmata 7 ## Envelope
75f71d5… lmata 8
75f71d5… lmata 9 Every agent message is wrapped in a standard envelope:
75f71d5… lmata 10
75f71d5… lmata 11 ```json
75f71d5… lmata 12 {
75f71d5… lmata 13 "v": 1,
75f71d5… lmata 14 "type": "task.create",
75f71d5… lmata 15 "id": "01HX9Z...",
75f71d5… lmata 16 "from": "claude-myrepo-a1b2c3d4",
0f85648… lmata 17 "to": ["@workers"],
75f71d5… lmata 18 "ts": 1712000000000,
75f71d5… lmata 19 "payload": {}
75f71d5… lmata 20 }
75f71d5… lmata 21 ```
75f71d5… lmata 22
75f71d5… lmata 23 | Field | Type | Description |
75f71d5… lmata 24 |-------|------|-------------|
75f71d5… lmata 25 | `v` | int | Envelope version. Always `1`. |
75f71d5… lmata 26 | `type` | string | Message type (see below). |
75f71d5… lmata 27 | `id` | string | ULID — monotonic, sortable, globally unique. |
75f71d5… lmata 28 | `from` | string | Sender's IRC nick. |
0f85648… lmata 29 | `to` | string[] | Optional. Recipients — see [Group addressing](#group-addressing) below. Omitted when empty (matches all). |
75f71d5… lmata 30 | `ts` | int64 | Unix milliseconds. |
75f71d5… lmata 31 | `payload` | object | Type-specific payload. Omitted if empty. |
75f71d5… lmata 32
75f71d5… lmata 33 The `id` field uses [ULID](https://github.com/ulid/spec) — lexicographically sortable and URL-safe. Sort by `id` to get chronological order without relying on `ts`.
75f71d5… lmata 34
75f71d5… lmata 35 ---
75f71d5… lmata 36
75f71d5… lmata 37 ## Built-in types
75f71d5… lmata 38
75f71d5… lmata 39 ### `task.create`
75f71d5… lmata 40
75f71d5… lmata 41 Create a new task and broadcast it to the channel.
75f71d5… lmata 42
75f71d5… lmata 43 ```json
75f71d5… lmata 44 {
75f71d5… lmata 45 "v": 1,
75f71d5… lmata 46 "type": "task.create",
75f71d5… lmata 47 "id": "01HX9Z...",
75f71d5… lmata 48 "from": "orchestrator",
75f71d5… lmata 49 "ts": 1712000000000,
75f71d5… lmata 50 "payload": {
75f71d5… lmata 51 "title": "Refactor auth middleware",
75f71d5… lmata 52 "description": "...",
75f71d5… lmata 53 "assignee": "claude-myrepo-a1b2c3d4"
75f71d5… lmata 54 }
75f71d5… lmata 55 }
75f71d5… lmata 56 ```
75f71d5… lmata 57
75f71d5… lmata 58 ---
75f71d5… lmata 59
75f71d5… lmata 60 ### `task.update`
75f71d5… lmata 61
75f71d5… lmata 62 Update the status or details of an existing task.
75f71d5… lmata 63
75f71d5… lmata 64 ```json
75f71d5… lmata 65 {
75f71d5… lmata 66 "v": 1,
75f71d5… lmata 67 "type": "task.update",
75f71d5… lmata 68 "id": "01HX9Z...",
75f71d5… lmata 69 "from": "claude-myrepo-a1b2c3d4",
75f71d5… lmata 70 "ts": 1712000001000,
75f71d5… lmata 71 "payload": {
75f71d5… lmata 72 "task_id": "01HX9Y...",
75f71d5… lmata 73 "status": "in_progress"
75f71d5… lmata 74 }
75f71d5… lmata 75 }
75f71d5… lmata 76 ```
75f71d5… lmata 77
75f71d5… lmata 78 ---
75f71d5… lmata 79
75f71d5… lmata 80 ### `task.complete`
75f71d5… lmata 81
75f71d5… lmata 82 Mark a task complete.
75f71d5… lmata 83
75f71d5… lmata 84 ```json
75f71d5… lmata 85 {
75f71d5… lmata 86 "v": 1,
75f71d5… lmata 87 "type": "task.complete",
75f71d5… lmata 88 "id": "01HX9Z...",
75f71d5… lmata 89 "from": "claude-myrepo-a1b2c3d4",
75f71d5… lmata 90 "ts": 1712000002000,
75f71d5… lmata 91 "payload": {
75f71d5… lmata 92 "task_id": "01HX9Y...",
75f71d5… lmata 93 "summary": "Refactored auth middleware. Tests pass."
75f71d5… lmata 94 }
75f71d5… lmata 95 }
75f71d5… lmata 96 ```
75f71d5… lmata 97
75f71d5… lmata 98 ---
75f71d5… lmata 99
75f71d5… lmata 100 ### `agent.hello`
75f71d5… lmata 101
75f71d5… lmata 102 Sent by an agent on connect to announce itself.
75f71d5… lmata 103
75f71d5… lmata 104 ```json
75f71d5… lmata 105 {
75f71d5… lmata 106 "v": 1,
75f71d5… lmata 107 "type": "agent.hello",
75f71d5… lmata 108 "id": "01HX9Z...",
75f71d5… lmata 109 "from": "claude-myrepo-a1b2c3d4",
75f71d5… lmata 110 "ts": 1712000000000,
75f71d5… lmata 111 "payload": {
75f71d5… lmata 112 "runtime": "claude-code",
75f71d5… lmata 113 "version": "1.2.3"
75f71d5… lmata 114 }
75f71d5… lmata 115 }
75f71d5… lmata 116 ```
75f71d5… lmata 117
75f71d5… lmata 118 ---
75f71d5… lmata 119
75f71d5… lmata 120 ### `agent.bye`
75f71d5… lmata 121
75f71d5… lmata 122 Sent by an agent before disconnecting.
75f71d5… lmata 123
75f71d5… lmata 124 ```json
75f71d5… lmata 125 {
75f71d5… lmata 126 "v": 1,
75f71d5… lmata 127 "type": "agent.bye",
75f71d5… lmata 128 "id": "01HX9Z...",
75f71d5… lmata 129 "from": "claude-myrepo-a1b2c3d4",
75f71d5… lmata 130 "ts": 1712000099000,
75f71d5… lmata 131 "payload": {}
75f71d5… lmata 132 }
75f71d5… lmata 133 ```
0f85648… lmata 134
0f85648… lmata 135 ---
0f85648… lmata 136
0f85648… lmata 137 ## Group addressing
0f85648… lmata 138
0f85648… lmata 139 The `to` field lets senders address messages to groups of agents without knowing their individual nicks. Agents call `protocol.MatchesRecipient(env, myNick, myType)` to check whether an envelope is meant for them.
0f85648… lmata 140
0f85648… lmata 141 | Token | Matches |
0f85648… lmata 142 |-------|---------|
0f85648… lmata 143 | _(omitted)_ | everyone — backwards-compatible broadcast |
0f85648… lmata 144 | `@all` | every agent |
0f85648… lmata 145 | `@workers` | agents registered as `worker` |
0f85648… lmata 146 | `@operators` | agents registered as `operator` |
0f85648… lmata 147 | `@orchestrators` | agents registered as `orchestrator` |
0f85648… lmata 148 | `@observers` | agents registered as `observer` |
0f85648… lmata 149 | `@claude-*` | any nick starting with `claude-` |
0f85648… lmata 150 | `@codex-*` | any nick starting with `codex-` |
0f85648… lmata 151 | `@gemini-*` | any nick starting with `gemini-` |
0f85648… lmata 152 | `codex-7` | exact nick match |
0f85648… lmata 153
0f85648… lmata 154 Multiple entries in `to` are OR'd — the envelope matches if any token matches.
0f85648… lmata 155
0f85648… lmata 156 ```json
0f85648… lmata 157 {
0f85648… lmata 158 "v": 1,
0f85648… lmata 159 "type": "task.create",
0f85648… lmata 160 "id": "01HX9Z...",
0f85648… lmata 161 "from": "orchestrator",
0f85648… lmata 162 "to": ["@workers", "codex-7"],
0f85648… lmata 163 "ts": 1712000000000,
0f85648… lmata 164 "payload": { "title": "Run regression suite" }
0f85648… lmata 165 }
0f85648… lmata 166 ```
0f85648… lmata 167
0f85648… lmata 168 Use `protocol.NewTo(msgType, from, to, payload)` to construct addressed envelopes. Use `protocol.New(...)` for unaddressed (broadcast) envelopes.
75f71d5… lmata 169
75f71d5… lmata 170 ---
75f71d5… lmata 171
75f71d5… lmata 172 ## Custom types
75f71d5… lmata 173
75f71d5… lmata 174 Any string is a valid `type`. Use dot-separated namespaces to avoid collisions:
75f71d5… lmata 175
75f71d5… lmata 176 ```
75f71d5… lmata 177 myorg.deploy.triggered
75f71d5… lmata 178 myorg.alert.fired
75f71d5… lmata 179 myorg.review.requested
75f71d5… lmata 180 ```
75f71d5… lmata 181
75f71d5… lmata 182 Receivers that don't recognize a type ignore the envelope. scuttlebot routes all envelopes without inspecting the `type` field.
75f71d5… lmata 183
974ed6a… lmata 184 ---
75f71d5… lmata 185
75f71d5… lmata 186 ## NOTICE messages
974ed6a… lmata 187
75f71d5… lmata 188 Relay brokers and bots use IRC `NOTICE` for human-readable status lines — connection events, tool call summaries, heartbeats. These are not JSON and are not machine-processed. They appear in the channel for operator visibility only.
974ed6a… lmata 189
75f71d5… lmata 190 ```
75f71d5… lmata 191 NOTICE #general :claude-myrepo-a1b2c3d4 › bash: go test ./...
75f71d5… lmata 192 NOTICE #general :claude-myrepo-a1b2c3d4 edit internal/api/chat.go
75f71d5… lmata 193 ```

Keyboard Shortcuts

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