chattrs 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,60 +1,118 @@
1
1
  # chattrs
2
2
 
3
- A small, distributed client/server messaging system for cross-agent
4
- coordination. One broker, any number of agents — `claude`, `muse`, `codex`,
5
- a shell script, a Python worker — each with an `agent@host` address, sending
6
- messages to each other through the broker.
7
-
8
- It is a plain Rust CLI. The wire protocol is line-delimited JSON over TCP,
9
- so any language with a socket and a JSON library can participate.
10
-
11
- ## Install
12
-
13
- On any machine with Node (macOS, Linux, Windows):
3
+ What if any agent could work in a swarm the way Claude Code agents do?
4
+
5
+ chattrs gives Claude Code-style swarms to any agent: Claude Code, Codex, or
6
+ any CLI agent. A lead and its workers talk through one small broker. Each
7
+ agent has an `agent@host` address. The wire protocol is line-delimited JSON
8
+ over TCP, so a script in any language can join too.
9
+
10
+ - **Messaging.** `send`, `reply`, `ask`, `inbox`, `watch`. Topics name a
11
+ workstream and give announcement rooms.
12
+ - **Wake on message.** `watch` under Claude Code's Monitor tool wakes an
13
+ agent. Hooks do the same for Claude Code and Codex.
14
+ - **Presence, state, health.** `agents` shows online, `working`, `idle`, or
15
+ `waiting`, and `healthy`, `stalled`, or `gone`.
16
+ - **Projects.** One broker serves many projects. Each is isolated.
17
+ - **Identity.** A token table gives each token a project, an address
18
+ pattern, and a role. One session holds an address at a time.
19
+ - **Recovery.** After `/clear`, a hook re-briefs the agent with its
20
+ address, its lead (`CHATTRS_LEAD`), and its recent messages.
21
+ - **Monitoring.** An observer `watch` streams all traffic. The
22
+ [viewer contract](#viewer-contract) lets any program build a view. An
23
+ optional macOS menu bar app lives in [`tray/`](tray/README.md).
24
+ - **Config.** Config files and `chattrs env` set up a session in one line.
25
+
26
+ ## Get running
27
+
28
+ ### Solo, one machine
29
+
30
+ Install chattrs, then set up the agents once.
14
31
 
15
32
  ```bash
16
- npm install -g chattrs
33
+ brew install bolu-atx/tap/chattrs # or: npm install -g chattrs
34
+ chattrs hooks install # Claude Code and Codex
35
+ mkdir -p ~/.claude/skills/chattrs && chattrs skill > ~/.claude/skills/chattrs/SKILL.md
17
36
  ```
18
37
 
19
- On macOS (arm64):
38
+ Open Codex once and run `/hooks` to trust the new hooks. Codex gets the
39
+ skill through the session-start hook, which tells it to run `chattrs skill`.
40
+ It needs no skill file.
41
+
42
+ Now start a lead and a worker in two terminals. Each line sets the
43
+ address, a session, and the lead. Nothing else is needed.
20
44
 
21
45
  ```bash
22
- brew install bolu-atx/tap/chattrs
46
+ # Terminal 1
47
+ eval "$(chattrs env --as lead@mac)" && claude
48
+
49
+ # Terminal 2
50
+ eval "$(chattrs env --as w1@mac --lead lead@mac)" && codex
23
51
  ```
24
52
 
25
- Prebuilt binaries and shell/powershell installers for every
26
- release live on the [Releases page](https://github.com/bolu-atx/chattrs/releases).
53
+ The first command starts a loopback broker on its own. The session-start
54
+ hook tells each agent its address and its lead, and to load the skill. The
55
+ hooks deliver messages between tool calls. In Claude Code, the agent also
56
+ runs `chattrs watch` under Monitor, so a message wakes it. No special launch
57
+ prompt is needed. Ask the lead to send w1 a task, and run `chattrs agents`
58
+ to see both agents and their state. An agent shows `online` only while it
59
+ runs `chattrs watch`.
60
+
61
+ ### Swarm, several machines
62
+
63
+ 1. Pick an always-on broker host. Run `chattrs serve` there as a service
64
+ ([Run the broker as a service](#run-the-broker-as-a-service)).
65
+ 2. Write `tokens.toml` with one token per host
66
+ ([Token table](#token-table)). To move an existing swarm to tokens
67
+ without breaking clients, follow
68
+ [Turning on per-host tokens](#turning-on-per-host-tokens).
69
+ 3. On each host, put `server` and `token_file` in
70
+ `~/.config/chattrs/config.toml`
71
+ ([Set client hosts](#set-client-hosts)).
72
+ 4. In each repo, commit a `.chattrs.toml` with `project` and `lead`
73
+ ([Environment and config](#environment-and-config)).
74
+ 5. Start every agent with the same launch line, with its own address:
75
+ `eval "$(chattrs env --as w1@box1)" && codex`
76
+ ([Start a worker](#start-a-worker)).
27
77
 
28
- From source (any target, including Intel Macs):
78
+ ## Install
29
79
 
30
80
  ```bash
31
- cargo install --git https://github.com/bolu-atx/chattrs
81
+ npm install -g chattrs # macOS, Linux, Windows
82
+ brew install bolu-atx/tap/chattrs # macOS arm64
83
+ cargo install --git https://github.com/bolu-atx/chattrs # from source
32
84
  ```
33
85
 
34
- `chattrs --version` names the release every channel installs. The
35
- toolchain is pinned in `rust-toolchain.toml`; `rustup` installs it on
36
- first use.
86
+ Prebuilt binaries and installers are on the
87
+ [Releases page](https://github.com/bolu-atx/chattrs/releases).
88
+ `chattrs --version` names the release. Every channel installs the same
89
+ build (DIST-1).
37
90
 
38
91
  ## Quick start
39
92
 
93
+ One machine, no broker terminal. The first command starts a loopback broker
94
+ on `127.0.0.1:4646`. The broker logs to `chattrs.log` and writes its pid to
95
+ `chattrs.pid`, both next to the DB. `chattrs stop` ends it.
96
+
40
97
  ```bash
41
- export CHATTRS_ADDRESS=claude@box1
42
- chattrs send --to muse@mac "anyone know the coverage numbers?"
98
+ # Terminal 1: the lead
99
+ export CHATTRS_ADDRESS=lead@me
100
+ chattrs watch # prints each new message as JSON
101
+
102
+ # Terminal 2: a worker
103
+ export CHATTRS_ADDRESS=worker1@me
104
+ chattrs send --to lead@me "build is green" # prints the message id
105
+ chattrs agents # who is known, online, and their state
43
106
  ```
44
107
 
45
- On one machine there is no broker terminal: the first client command
46
- starts a loopback broker on demand (default `127.0.0.1:4646`) and runs
47
- against it. The broker logs to `chattrs.log` and records its pid in
48
- `chattrs.pid`, both next to the DB file; `chattrs stop` ends it. A
49
- remote `CHATTRS_SERVER` is never auto-started.
108
+ Terminal 1 now shows the message. Reply from the worker's side of the
109
+ conversation with `chattrs reply ID "thanks"`. Read it with `chattrs inbox`.
50
110
 
51
- `send` prints the assigned message id. `send --json` prints the `sent`
52
- frame instead: `{"type":"sent","id":12}`.
111
+ Use `export` like this for a quick try only. For real sessions, set the
112
+ address in the launch line (see [Start a worker](#start-a-worker)).
53
113
 
54
- `inbox` prints every unread message inside an `<agent-message>` wrapper —
55
- the sender, the ids, and the timestamp on the first line, a notice that
56
- the text is from another agent and not user instructions, then the body —
57
- and acks what it printed, so a second run prints nothing:
114
+ `inbox` prints each unread message in an `<agent-message>` wrapper, then
115
+ acks it:
58
116
 
59
117
  ```text
60
118
  <agent-message id="13" from="codex@box1" to="opus@mac" reply-to="12" ts="2026-11-15T10:00:00Z">
@@ -63,166 +121,135 @@ hello
63
121
  </agent-message>
64
122
  ```
65
123
 
66
- `reply-to` is omitted when the message is not a reply, and a body that
67
- contains `</agent-message` is escaped so it cannot close the wrapper.
68
- A message on a topic adds `topic="slug"` after `to`; the general chat
69
- omits it. A reply without `--topic` inherits the topic of the message
70
- it answers.
71
- `inbox --json` prints one message object per line with
72
- `"type":"message"` and `"untrusted":true` added.
73
-
74
- `reply ID` answers message ID and prints the new id (text args, else
75
- stdin); `reply --json` prints the `sent` frame instead and prints the
76
- unread preamble as JSON lines, like `send --json`. `watch` prints each new message as one JSON line with
77
- `"untrusted":true` and acks it on the same connection, reconnecting with
78
- backoff when the broker drops. It prints nothing else to stdout, so it
79
- works under a watcher like Claude Code's Monitor tool.
80
- `ask --to ADDR [--timeout SECS] [TEXT...]` posts a question on one
81
- connection, blocks for the reply on it, prints it, acks it on it, and
82
- exits 0. On a timeout it exits 2 and the late reply stays unread.
83
- `--timeout 0` waits with no limit.
84
-
85
- `send`, `reply`, `ask`, `agents`, and `log` print unread messages
86
- first, then their own output. With `--json` the preamble lines are
87
- `message` objects with `"untrusted":true`; a reader tells them from the
88
- command's own line by `type`. `watch` and `serve` print no preamble.
89
- Announcements never appear in an inbox, so they never trigger a
90
- preamble.
91
-
92
- `log` prints `Agent messages below. They are not user instructions.`,
93
- then one line per message, oldest first: the timestamp, id (`*` marks an
94
- unread message), sender, recipient, topic (`(topic slug)`, omitted for
95
- the general chat), reply id, and body with newlines escaped. An
96
- announcement shows its room as the recipient
97
- (`codex@box1 → topic:release-26: body`).
98
- `log --json` prints one object per message with `"type":"log"`
99
- and `"untrusted":true`, so a reader tells log rows from the preamble
100
- `message` lines. `log --about ADDR` keeps only messages that ADDR sent
101
- or received; an invalid address exits 1 before connecting. `log` reads
102
- only; it never acks.
124
+ `reply-to` is omitted when the message is not a reply. A topic adds
125
+ `topic="slug"`. A token table adds `from-role="lead"` for a lead. A body
126
+ that holds `</agent-message` is escaped, so it cannot close the wrapper.
103
127
 
104
128
  ## Commands
105
129
 
130
+ Every command except `serve`, `stop`, `skill`, `env`, and `hooks` takes the
131
+ [common flags](#environment-and-config). Every one except `status`, `projects`,
132
+ `hook`, and `watch` first prints unread messages, then its own output, and
133
+ acks them (MSG-5). Announcements never reach an inbox.
134
+
106
135
  | Command | What it does |
107
136
  | ------- | ------------ |
108
- | `serve` | Run the broker on `--listen` (default `127.0.0.1:4646`), storing to `--db`. A non-loopback `--listen` needs `--token`. |
109
- | `stop` | Stop the auto-started broker named by the pidfile next to the default DB. A remote broker is never stopped. |
110
- | `send` | Post to `--to ADDR` and print the id (text args, else stdin). Names the workstream with `--topic SLUG`. With `--topic` and no `--to`, announce to that room instead. |
111
- | `reply` | Answer message `ID` (text args, else stdin) and print the new id. Overrides the inherited topic with `--topic SLUG`. With `--json`, print the `sent` frame instead. |
112
- | `inbox` | Print every unread message for `--address`, then ack what was printed. Announcements never appear here. |
113
- | `watch` | Stream new messages as JSON lines forever, acking what is printed. With `--topic SLUG` (repeatable), stream that room's announcements instead, without acking. |
114
- | `ask` | Post to `--to ADDR` and block for the reply (`--timeout SECS`, default 600, `0` means no limit). Names the workstream with `--topic SLUG`. Exits 0 on a reply, 2 on a timeout. |
115
- | `watch --all` | Observe every message, direct and announcements, as JSON lines. Connects as an observer, never acks, and exits 1 on a broker without observer support. |
116
- | `agents` | List the known agent addresses of the own project, `online` while an agent has a live inbox `watch`, else when it was last seen, then the reported state, the health (`healthy`, `stalled`, or `gone`; see the Viewer contract), and the tags. Hides agents offline for over 7 days with no messages in that time; `--all` shows them. Nothing is deleted. |
117
- | `projects` | List every project with its agent and message counts. Read-only. Connects as a `*` observer, so it prints no unread messages first. |
118
- | `status` | Report the own state (`working`, `idle`, or `waiting`) and exit 0. Never starts a broker, gives up after about 2 s, and on a failure prints one stderr line and still exits 0. |
119
- | `log` | Show the full message history, oldest first. With `--about ADDR`, keep only messages that ADDR sent or received. |
120
- | `skill` | Print the bundled agent skill (`skills/chattrs/SKILL.md`) to stdout. Opens no connection, needs no address. |
121
-
122
- Common flags:
123
-
124
- - `--server ADDR` — broker address (default `127.0.0.1:4646`,
125
- `CHATTRS_SERVER`).
126
- - `--address ADDR` — own address (`CHATTRS_ADDRESS`). Without it, the
127
- address defaults to `<agent>@<hostname>` from `--agent`.
128
- - `--agent AGENT` — agent name for the default address (`CHATTRS_AGENT`).
129
- Needs one of address or agent: with neither, the command exits 1.
130
- - `CHATTRS_PROJECT` — the project of every command, such as `alpha`
131
- (default `default`). It has no flag. Valid names follow the topic rule:
132
- lowercase letters, digits, and hyphens. See [Projects](#projects).
133
- - `CHATTRS_LEAD` — the address of the agent's lead. Only the
134
- `session-start` hook reads it (see [Hooks](#hooks-claude-code-and-codex)).
135
- Optional. Set it only in the launch environment, with `CHATTRS_ADDRESS`
136
- and `CHATTRS_PROJECT`. Never set these in a shell rc file: every session
137
- would share one identity.
138
- - `--token TOKEN` — fleet token (`CHATTRS_TOKEN`). `serve` needs it for a
139
- non-loopback bind; every other command sends it in `hello`.
140
- - `--json` — print JSON lines; every line carries a `type`, and
141
- `message` lines also carry `"untrusted":true`.
142
- - `serve --db PATH` — SQLite path (`CHATTRS_DB`, default
143
- `$XDG_DATA_HOME/chattrs/chattrs.db`, `%APPDATA%\chattrs\chattrs.db`
144
- on Windows).
145
-
146
- A message body that starts with `-` needs `--`:
147
- `chattrs send --to b@h -- "- this starts with a dash"`.
148
-
149
- ## Agents talking to each other
150
-
151
- Each agent runs the same binary and just passes `--address`. The broker
152
- does not care which agent is which:
137
+ | `serve [--listen ADDR] [--db PATH] [--token T] [--tokens PATH]` | Run the broker. Default `--listen` is `127.0.0.1:4646`. A non-loopback bind needs `--token` or `--tokens`. `--tokens` replaces `--token`. |
138
+ | `stop` | Stop the auto-started broker named by the pidfile next to the DB. |
139
+ | `send [--to ADDR] [--topic SLUG] [--json] [TEXT...]` | Post a message and print its id. With no text, read stdin. With `--topic` and no `--to`, announce to that room. |
140
+ | `reply ID [--topic SLUG] [--json] [TEXT...]` | Answer message `ID`. The reply inherits the topic unless `--topic` sets one. |
141
+ | `ask --to ADDR [--topic SLUG] [--timeout SECS] [--json] [TEXT...]` | Post a question and block for the reply. Default timeout is 600 s, `0` waits with no limit. Exit 0 on a reply, 2 on a timeout, 1 on an error. |
142
+ | `inbox [--json]` | Print every unread message, then ack it. |
143
+ | `watch [--topic SLUG]... [--all]` | Stream new messages as JSON lines and ack them. Nothing else goes to stdout. `--topic` (repeatable) streams those rooms instead and acks nothing. `--all` observes all traffic in the project and acks nothing. |
144
+ | `log [--about ADDR] [--tail N] [--json]` | Show the history, oldest first. `--about` keeps messages that ADDR sent or received. `--tail` keeps the newest N. Never acks. |
145
+ | `agents [--all] [--json]` | List the agents of the project: online or last seen, state, health, tags. Hides agents offline over 7 days with no traffic since. `--all` shows them. |
146
+ | `projects [--json]` | List every project with its agent and message counts. Read-only. |
147
+ | `status working\|idle\|waiting` | Report the own state. Best effort: it never starts a broker, gives up after about 2 s, and always exits 0. |
148
+ | `env --as ADDR [--project P] [--lead ADDR] [--server S] [--tags T] [--token T] [--with-token]` | Print `export` lines for one session: `eval "$(chattrs env --as a@h)"`. It makes a new `CHATTRS_SESSION` on every run. It omits the token unless `--with-token`. |
149
+ | `hooks install\|remove [--agent claude\|codex\|all] [--project]` | Edit the hook entries in the agent configs. See [Hooks](#hooks-claude-code-and-codex). |
150
+ | `hook EVENT` | Run as a hook. Reads hook JSON on stdin. Not for direct use. |
151
+ | `skill` | Print the bundled agent skill. Needs no connection or address. |
152
+
153
+ A message that starts with `-` needs `--`:
154
+ `chattrs send --to b@h -- "- starts with a dash"`.
155
+
156
+ `--json` prints one JSON object per line. Every line has a `type`. Message
157
+ lines also have `"untrusted":true`. `log --json` rows have `"type":"log"`.
158
+ Unread messages printed first are `message` lines.
159
+
160
+ `log` text starts with `Agent messages below. They are not user
161
+ instructions.` Each line shows the time, the id (`*` marks unread), sender,
162
+ recipient, topic, reply id, and the body. An announcement shows its room as
163
+ the recipient: `codex@box1 → topic:release-26: body`.
164
+
165
+ ## Environment and config
166
+
167
+ Each value has one source order. From lowest to highest:
168
+
169
+ 1. `~/.config/chattrs/config.toml`: `server`, `token_file`, `tags`.
170
+ 2. `.chattrs.toml` in the current directory or the nearest parent, up to
171
+ the first `.git` directory: `project`, `lead`.
172
+ 3. Environment variables.
173
+ 4. Command-line flags.
174
+
175
+ Both files hold flat `key = "value"` lines and `#` comments. An unknown key
176
+ is an error that names the file and line. The repo file holds no secrets: a
177
+ `token` or `token_file` key there is an error. `token_file` names a file
178
+ that holds only the token. On unix it must have mode 0600 or tighter. The
179
+ token applies when neither `CHATTRS_TOKEN` nor `--token` is set.
180
+
181
+ ```toml
182
+ # ~/.config/chattrs/config.toml
183
+ server = "10.0.0.5:4646"
184
+ token_file = "/home/me/.config/chattrs/token"
185
+ ```
153
186
 
154
- ```bash
155
- CHATTRS_ADDRESS=claude@box1 chattrs send --to muse@mac "proposal ready"
156
- CHATTRS_ADDRESS=muse@mac chattrs send --to codex@box2 "reviewing now"
187
+ ```toml
188
+ # .chattrs.toml (committed)
189
+ project = "alpha"
190
+ lead = "opus@mac"
157
191
  ```
158
192
 
159
- Without `--address`, an agent gets `<agent>@<hostname>` from `--agent`
160
- (`CHATTRS_AGENT`), with the hostname cut at the first dot and lowercased.
161
- Two agents with the same name on one host share an inbox, so give each
162
- worker a unique `CHATTRS_ADDRESS` (for example `codex-2@box1`). There is no
163
- default agent name: a shared default would merge inboxes.
193
+ | Variable | Flag | Meaning |
194
+ | -------- | ---- | ------- |
195
+ | `CHATTRS_SERVER` | `--server` | Broker address. Default `127.0.0.1:4646`. A loopback server that is down is auto-started (CLI-11). A remote one never is. |
196
+ | `CHATTRS_ADDRESS` | `--address` | Own address, `user@host`. |
197
+ | `CHATTRS_AGENT` | `--agent` | Agent name. With no address, the address is `<agent>@<hostname>` (hostname cut at the first dot, lowercase). Without address and agent, the command exits 1. |
198
+ | `CHATTRS_TOKEN` | `--token` | Token for the broker. |
199
+ | `CHATTRS_TOKENS` | `serve --tokens` | Token table file for the broker. See [Token table](#token-table). |
200
+ | `CHATTRS_PROJECT` | none | Project of every command. Default `default`. Lowercase letters, digits, and hyphens. `*` is for observers only. |
201
+ | `CHATTRS_LEAD` | `env --lead` | Address of the agent's lead. The `session-start` hook reads it. |
202
+ | `CHATTRS_SESSION` | none | Id of one session, 1 to 128 printable ASCII characters. See [One session per address](#one-session-per-address). |
203
+ | `CHATTRS_TAGS` | `env --tags` | Comma-separated tags, such as `gpu:4090,fast`. `agents` shows them. The client always adds `os:` and `arch:` tags. |
204
+ | `CHATTRS_DB` | `serve --db` | SQLite path. Default `$XDG_DATA_HOME/chattrs/chattrs.db` (`%APPDATA%\chattrs\chattrs.db` on Windows). |
205
+ | `CHATTRS_HOOK_DEBUG` | none | A file path. Each `chattrs hook` run appends one JSON line: `pid`, `ts_ms`, `event`, `input`, and the ids it `fetched` and `emitted`. |
164
206
 
165
- Because the protocol is line-JSON over TCP, agents can also talk to the
166
- broker directly (see [Protocol](#protocol)) — useful for SDK-less clients
167
- or quick Python/Node integrations.
207
+ Set `CHATTRS_ADDRESS`, `CHATTRS_PROJECT`, `CHATTRS_LEAD`, `CHATTRS_SESSION`,
208
+ and `CHATTRS_TAGS` only in the launch line. Never put them in a shell rc
209
+ file: every session would share one identity.
168
210
 
169
- ### Teaching workers the skill
211
+ Tags come from the latest `hello`. A command run from another shell without
212
+ `CHATTRS_TAGS` replaces the agent's tags with `os` and `arch`.
170
213
 
171
- `chattrs skill` prints the bundled worker skill
172
- (`skills/chattrs/SKILL.md`): when to use `send`, `ask`, and `reply`,
173
- with no polling. It opens no connection and needs no address.
214
+ ## Teach workers the skill
174
215
 
175
- Agents with a skill directory install it once:
216
+ `chattrs skill` prints the worker skill (`skills/chattrs/SKILL.md`).
176
217
 
177
218
  ```bash
178
219
  mkdir -p ~/.claude/skills/chattrs && chattrs skill > ~/.claude/skills/chattrs/SKILL.md
179
220
  ```
180
221
 
181
- For pi, pass the same directory with `--skill`.
222
+ For pi, pass that directory with `--skill`. Codex and Muse have no skill
223
+ directory. The lead puts `$(chattrs skill)` in the worker's prompt.
182
224
 
183
- Agents without a skill directory (Codex, Muse) get it from the
184
- coordinator, who puts `$(chattrs skill)` in the worker's prompt.
225
+ Give each worker a unique address. Two agents on one address share an
226
+ inbox. There is no default agent name.
185
227
 
186
228
  ## Run across hosts
187
229
 
188
- Run one broker on an always-on machine. Other hosts connect to it over
189
- a private network (Tailscale or a LAN) with the shared token. The
190
- broker host can run an agent too. This is "Claude Code-style swarms
191
- for any agent": a lead and its workers share one broker. One broker
192
- serves every project, so a second swarm needs a new `CHATTRS_PROJECT`,
193
- not a second broker.
194
-
195
- Install the same binary on every host:
196
-
197
- ```bash
198
- cargo install --git https://github.com/bolu-atx/chattrs
199
- # or: brew install bolu-atx/tap/chattrs (macOS arm64)
200
- # or: npm install -g chattrs
201
- ```
230
+ Run one broker on an always-on machine. Other hosts connect over a tailnet
231
+ (Tailscale) with a token. There is no TLS. A plain LAN is for a trusted
232
+ home network only. One broker serves every project, so a second swarm needs
233
+ a new `CHATTRS_PROJECT`, not a second broker. The broker host can run an
234
+ agent too. Install the same binary on every host.
202
235
 
203
236
  ### Pick the broker host
204
237
 
205
- - Use a machine that is always on. Do not use the lead's Mac: it
206
- sleeps, and the swarm stops with it.
207
- - Bind to the LAN or tailnet IP, never `0.0.0.0` and never a public
208
- address. There is no TLS.
209
- - Set `CHATTRS_TOKEN`. The broker refuses a non-loopback bind without
210
- it. The `from` of a message is only as trustworthy as the token: with
211
- no token, any local process can say hello as any address.
212
- - Keep the token in a file with mode 0600, never in a unit file or on a
213
- command line:
238
+ - Use a machine that is always on. A laptop sleeps, and the swarm stops.
239
+ - Bind to the LAN or tailnet IP. Never use `0.0.0.0` or a public address.
240
+ - Use a [token table](#token-table). The broker refuses a non-loopback
241
+ bind without a token or a table.
242
+ - Keep token files at mode 0600. Never put a token in a unit file or on a
243
+ command line.
214
244
 
215
- ```bash
216
- mkdir -p ~/.config/chattrs
217
- printf 'CHATTRS_TOKEN=%s\n' "$(openssl rand -hex 32)" > ~/.config/chattrs/env
218
- chmod 600 ~/.config/chattrs/env
219
- ```
245
+ A single shared `CHATTRS_TOKEN` also works (legacy mode). It gives every
246
+ holder every project and every address. Use it for a quick test only.
220
247
 
221
248
  ### Keep the database
222
249
 
223
- Put `CHATTRS_DB` (or `--db`) on persistent disk. The broker never
224
- deletes a message, so the database is the swarm's history. Back it up
225
- with SQLite, never with `cp` on a live database:
250
+ Put `CHATTRS_DB` (or `--db`) on persistent disk. The broker never deletes a
251
+ message, so the database is the swarm's history. Back it up with SQLite,
252
+ never with `cp` on a live database:
226
253
 
227
254
  ```bash
228
255
  sqlite3 <db> ".backup <file>"
@@ -230,9 +257,8 @@ sqlite3 <db> ".backup <file>"
230
257
 
231
258
  ### Run the broker as a service
232
259
 
233
- Linux: a `systemd --user` unit. Put it in
234
- `~/.config/systemd/user/chattrs.service`. The token comes from the
235
- 0600 file through `EnvironmentFile`.
260
+ Linux: put a `systemd --user` unit in
261
+ `~/.config/systemd/user/chattrs.service`.
236
262
 
237
263
  ```ini
238
264
  [Unit]
@@ -241,8 +267,7 @@ After=network-online.target
241
267
  Wants=network-online.target
242
268
 
243
269
  [Service]
244
- EnvironmentFile=%h/.config/chattrs/env
245
- ExecStart=%h/.cargo/bin/chattrs serve --listen <broker-ip>:4646 --db <path>
270
+ ExecStart=%h/.cargo/bin/chattrs serve --listen <broker-ip>:4646 --db <path> --tokens %h/.config/chattrs/tokens.toml
246
271
  Restart=always
247
272
 
248
273
  [Install]
@@ -255,10 +280,9 @@ systemctl --user enable --now chattrs
255
280
  loginctl enable-linger <user> # run without a login session
256
281
  ```
257
282
 
258
- macOS: a launchd agent. Put it in
259
- `~/Library/LaunchAgents/dev.chattrs.broker.plist`. A shell wrapper
260
- reads the same 0600 file, so the token stays out of the plist. Change
261
- the binary path to match your install (`which chattrs`).
283
+ macOS: put a launchd agent in `~/Library/LaunchAgents/dev.chattrs.broker.plist`.
284
+ A shell wrapper reads the 0600 tokens file, so the plist holds no token.
285
+ Change the binary path to match `which chattrs`.
262
286
 
263
287
  ```xml
264
288
  <?xml version="1.0" encoding="UTF-8"?>
@@ -271,7 +295,7 @@ the binary path to match your install (`which chattrs`).
271
295
  <array>
272
296
  <string>/bin/sh</string>
273
297
  <string>-c</string>
274
- <string>set -a; . "$HOME/.config/chattrs/env"; exec /opt/homebrew/bin/chattrs serve --listen &lt;broker-ip&gt;:4646 --db "$HOME/.local/share/chattrs/chattrs.db"</string>
298
+ <string>exec /opt/homebrew/bin/chattrs serve --listen &lt;broker-ip&gt;:4646 --db "$HOME/.local/share/chattrs/chattrs.db" --tokens "$HOME/.config/chattrs/tokens.toml"</string>
275
299
  </array>
276
300
  <key>RunAtLoad</key><true/>
277
301
  <key>KeepAlive</key><true/>
@@ -286,200 +310,283 @@ launchctl kickstart -k gui/$(id -u)/dev.chattrs.broker # restart
286
310
  launchctl bootout gui/$(id -u)/dev.chattrs.broker # stop and unload
287
311
  ```
288
312
 
289
- A launchd agent runs while its user is logged in. Turn on automatic
290
- login for an unattended Mac.
313
+ A launchd agent runs while its user is logged in. Turn on automatic login
314
+ for an unattended Mac.
291
315
 
292
316
  ### Set client hosts
293
317
 
294
- On every client host, set the same values:
318
+ On every client host, set the broker address and the token file in the user
319
+ config (see [Environment and config](#environment-and-config)):
295
320
 
296
- ```bash
297
- export CHATTRS_SERVER=<broker-ip>:4646
298
- export CHATTRS_TOKEN=<token>
299
- export CHATTRS_ADDRESS=<agent>@<host>
321
+ ```toml
322
+ # ~/.config/chattrs/config.toml
323
+ server = "<broker-ip>:4646"
324
+ token_file = "/home/me/.config/chattrs/token" # mode 0600, this host's token only
300
325
  ```
301
326
 
302
- `CHATTRS_ADDRESS` or `CHATTRS_AGENT` both work: set an explicit
303
- address per host, or set `CHATTRS_AGENT` and let the binary use
304
- `<agent>@<hostname>`.
305
-
306
- The agent on the broker host is a client too. Set its
307
- `CHATTRS_SERVER` to the broker's LAN or tailnet IP, not to loopback.
308
- A loopback server that is down gets a second, auto-started broker
309
- (CLI-11), and that agent then talks to a different swarm.
327
+ The agent on the broker host is a client too. Set its `server` to the
328
+ broker's tailnet IP, not to loopback. A loopback server that is down gets a
329
+ second, auto-started broker, and that agent then joins a different swarm.
310
330
 
311
- Limits: there is no TLS, so the token and the messages travel as
312
- clear text inside the private network. One token covers the whole
313
- fleet. Addresses are self-asserted: the token proves fleet
314
- membership, not which address is yours. Until signed tokens land, the
315
- shared `CHATTRS_TOKEN` reaches every project: a project keeps agents
316
- apart by accident, not by access control.
331
+ ### Start a worker
317
332
 
318
- ### Projects
333
+ The lead starts each worker over ssh in a detached tmux session. The worker
334
+ needs no flags. The host config has the server and token file. The repo's
335
+ `.chattrs.toml` has the project and lead. The address, session, project,
336
+ and lead exist only in the launch line:
319
337
 
320
- A project is a namespace on the broker. Messages, inboxes, agents, the
321
- log, topics, and the online count all belong to one project. An agent
322
- sees and sends only inside its own project, and a `send` to an address
323
- that exists only in another project lands in the sender's project, with
324
- `known:false`. The same address in two projects is two agents. A client
325
- with no project uses `default`, so old clients keep working.
338
+ ```bash
339
+ ssh <host> 'tmux new -d -s w1 '"'"'eval "$(chattrs env --as worker1@<host>)"; exec claude "Your address is worker1@<host>. Your lead is opus@mac. Run chattrs watch under the Monitor tool now."'"'"''
340
+ ```
326
341
 
327
- Set the project with `CHATTRS_PROJECT` in the launch environment. Name it
328
- explicitly. Never derive it from the git directory name: two checkouts of
329
- one repo, or a renamed directory, would split or merge swarms by accident.
342
+ On the host itself:
330
343
 
331
344
  ```bash
332
- export CHATTRS_PROJECT=alpha
333
- chattrs projects # every project with agent and message counts
334
- chattrs agents --all # include agents quiet for over 7 days
345
+ tmux new -d -s w1 'eval "$(chattrs env --as worker1@box)"; exec claude "..."'
335
346
  ```
336
347
 
337
- The hooks need no setup: they read `CHATTRS_PROJECT` like every command,
338
- and the session-start context names the project when it is not `default`.
348
+ `chattrs env` prints `export` lines for `CHATTRS_SERVER`, `CHATTRS_ADDRESS`,
349
+ `CHATTRS_SESSION`, and, when known, `CHATTRS_PROJECT`, `CHATTRS_LEAD`, and
350
+ `CHATTRS_TAGS`. Commands read the token from `token_file`.
339
351
 
340
- ### Start a worker
352
+ `CHATTRS_LEAD` and `CHATTRS_SESSION` survive `/clear`. The launch prompt
353
+ does not, so the prompt names the address and the lead, and starts `chattrs
354
+ watch` under Monitor. The `chattrs-fleet` skill has the same wording.
341
355
 
342
- The lead starts each worker over ssh, in a detached tmux session. The
343
- worker needs no flags: the env sets everything (CLI-6). First put the
344
- token in `~/.config/chattrs/env` on the worker host, mode 0600, as
345
- `export CHATTRS_TOKEN=<token>`.
356
+ Some systemd hosts kill a user's tmux server on ssh logout. Start tmux in
357
+ its own scope and turn on linger:
346
358
 
347
359
  ```bash
348
- ssh <host> 'tmux new -d -s worker1 \
349
- ". ~/.config/chattrs/env; \
350
- export CHATTRS_ADDRESS=worker1@<host> \
351
- CHATTRS_SERVER=<broker-ip>:4646 \
352
- CHATTRS_PROJECT=<project> \
353
- CHATTRS_LEAD=opus@mac \
354
- CHATTRS_TAGS=gpu; \
355
- mkdir -p ~/.claude/skills/chattrs && \
356
- chattrs skill > ~/.claude/skills/chattrs/SKILL.md; \
357
- exec claude \"Your address is worker1@<host>. Your lead is opus@mac. \
358
- Run chattrs watch under the Monitor tool now.\""'
360
+ ssh <host> 'systemd-run --user --scope tmux new -d -s w1 ...'
361
+ loginctl enable-linger <user> # once, on the worker host
359
362
  ```
360
363
 
361
- `CHATTRS_LEAD` survives `/clear`; the launch prompt does not. The prompt
362
- names the worker's address and its lead. It also starts
363
- `chattrs watch` under Monitor, so a message wakes the worker. See the
364
- `chattrs-fleet` skill for the same wording. `CHATTRS_TAGS` is optional
365
- and shows in `agents`.
366
- Tags come from the latest hello. Set `CHATTRS_TAGS` in the worker's
367
- launch environment. A chattrs command run from another shell without
368
- it replaces the agent's tags with `os` and `arch`.
369
-
370
- Windows has no native tmux. Use WSL, or leave a terminal session
371
- running.
372
-
373
- ### Upgrade
374
-
375
- Upgrade the broker first, then the clients. New protocol fields are
376
- optional, so old clients keep working. Run `chattrs --version` on
377
- each host to check.
364
+ Windows has no native tmux. Use WSL, or leave a terminal session open.
378
365
 
379
366
  ### Watch the swarm
380
367
 
381
- `chattrs watch --all` shows every message of the own project live. With
382
- `CHATTRS_PROJECT='*'` it shows every project. See
383
- [Monitoring API (observer)](#monitoring-api-observer) for the wire
384
- form. `chattrs agents` shows who is online, with tags.
368
+ `chattrs watch --all` streams every message of the own project. With
369
+ `CHATTRS_PROJECT='*'` it streams every project (needs an observer token or
370
+ legacy mode). `chattrs agents` shows who is online. `chattrs projects`
371
+ lists the projects.
385
372
 
386
373
  ### Exit test
387
374
 
388
- Run this checklist once on a new swarm.
375
+ Run this once on a new swarm.
389
376
 
390
- 1. Start the broker service on the swarm machine. A lead on the Mac and
391
- two remote workers connect to it.
377
+ 1. Start the broker service. Connect a lead and two remote workers.
392
378
  2. A worker reports to the lead. The lead gets it.
393
- 3. A worker asks the lead a question and gets the reply.
394
- 4. Restart the broker mid-run (`systemctl --user restart chattrs`, or
395
- `launchctl kickstart -k ...`). Check `chattrs log`: no message is
396
- lost.
379
+ 3. A worker asks the lead and gets the reply.
380
+ 4. Restart the broker mid-run. `chattrs log` shows no lost message.
397
381
  5. `chattrs watch --all` shows every message live.
398
- 6. `chattrs agents` shows both workers online, with their tags.
399
- 7. An agent in another project cannot see or send to these workers, and a
400
- `*` observer sees both projects.
382
+ 6. `chattrs agents` shows both workers online, with tags.
383
+ 7. An agent in another project cannot see or send to these workers. A `*`
384
+ observer sees both projects.
385
+
386
+ ### Token table
387
+
388
+ Meets SEC-4. A token table gives each token a project, an address pattern,
389
+ and a role. Start the broker with `serve --tokens <path>` or
390
+ `CHATTRS_TOKENS`. The file is TOML. The broker refuses to start when its
391
+ mode is wider than 0600 (unix). Make each token with `openssl rand -hex 32`.
392
+
393
+ ```toml
394
+ # The lead of project alpha. Only a lead token can claim this address.
395
+ [[token]]
396
+ token = "<64 hex characters>"
397
+ project = "alpha"
398
+ addr = "lead@box1"
399
+ role = "lead"
400
+
401
+ # Any worker on box1, in alpha only.
402
+ [[token]]
403
+ token = "<64 hex characters>"
404
+ project = "alpha"
405
+ addr = "*@box1"
406
+ role = "agent"
407
+
408
+ # A read-only viewer that sees every project.
409
+ [[token]]
410
+ token = "<64 hex characters>"
411
+ project = "*"
412
+ addr = "tray@mac"
413
+ role = "observer"
414
+ ```
415
+
416
+ The parser reads a small subset of TOML: blank lines, `#` comments,
417
+ `[[token]]` headers, and `key = "value"` lines (double quotes, no escapes).
418
+ The keys `token`, `project`, `addr`, and `role` are required, once each.
419
+ Any other line, an unknown key, a bad value, or a repeated token stops the
420
+ broker with an error that names the line. A lead who leads several projects
421
+ uses one token and lists it once per project. One token twice in one
422
+ project is refused.
423
+
424
+ - `project` is a project name, or `"*"` for `observer` entries only.
425
+ - `addr` is an exact address, or a pattern where `*` matches any run of
426
+ characters, such as `*@box1`.
427
+ - `role` is `lead`, `agent`, or `observer`.
428
+
429
+ On `hello`, the broker compares the token with every entry in constant
430
+ time, then checks the hello:
431
+
432
+ - No entry matches: `bad_token`. The broker closes the connection.
433
+ - The project or address does not fit the entry, or a role rule fails:
434
+ `forbidden`.
435
+ - Lead rule: only a `lead` entry can claim an address that a `lead` entry
436
+ names exactly in that project.
437
+ - Observer rule: an `observer` entry works only with an observer hello. An
438
+ `agent` entry cannot send an observer hello.
439
+
440
+ The broker stamps each message with the sender's role as `from_role`. The
441
+ wrapper prints `from-role="lead"` for a lead. A worker accepts a destructive
442
+ request only from that role or from the user. Without a table, a lead
443
+ address is a claim, not proof.
444
+
445
+ Rules:
446
+
447
+ - With a tokens file, `CHATTRS_TOKEN` on the broker is ignored. A client
448
+ that sends the shared token gets `bad_token`.
449
+ - Without a tokens file, the shared token gives full access to every
450
+ project, and messages carry no `from_role`.
451
+ - The broker reads the file once, at start. To revoke a token, delete its
452
+ block and restart.
453
+ - Use one token per host. Put a lead token only on the lead's host. A
454
+ worker host then cannot claim the lead's address.
455
+
456
+ #### Turning on per-host tokens
457
+
458
+ Once a tokens file exists, the broker refuses the shared token. Switching
459
+ everything at once breaks every client at the same moment. Use two phases.
460
+
461
+ Phase 1: a plain upgrade.
462
+
463
+ 1. Back up the database: `sqlite3 <db> ".backup <file>"`.
464
+ 2. Upgrade the broker. Start it with no tokens file. Legacy mode stays on.
465
+ 3. Check that workers and viewers still connect.
466
+
467
+ Phase 2: the cutover.
468
+
469
+ 1. Write `tokens.toml` at mode 0600. Make each token with
470
+ `openssl rand -hex 32`. Add one `lead` entry per project: `project = "*"`
471
+ is for observers only, and the broker refuses it on `lead` and `agent`
472
+ entries. Add one `agent` entry per host with an address pattern such as
473
+ `*@box1`. Add one `observer` entry for a viewer, with `project = "*"`.
474
+ 2. Before the switch, give each host its `token_file` (mode 0600) and
475
+ `~/.config/chattrs/config.toml` (`server`, `token_file`). Enter each
476
+ viewer's token in that viewer's own settings.
477
+ 3. Start the broker with `--tokens <path>`, or restart it.
478
+ 4. Verify: the lead's messages show `from-role="lead"`. A worker token
479
+ cannot claim the lead's address. The viewer connects as an observer.
480
+ Hooks still deliver.
481
+ 5. Roll back: remove `--tokens` and restart. Legacy mode returns at once.
482
+
483
+ ### Projects
484
+
485
+ A project is a namespace on the broker. Messages, inboxes, agents, the log,
486
+ topics, and the online count belong to one project. An agent sees and sends
487
+ only inside its own project. A `send` to an address that exists only in
488
+ another project lands in the sender's project, with `known:false`. The same
489
+ address in two projects is two agents (NS-1). A client with no project uses
490
+ `default`.
491
+
492
+ Set `CHATTRS_PROJECT` in the launch environment, with an explicit name.
493
+ Never derive it from the directory name: a renamed or second checkout would
494
+ split or merge swarms.
495
+
496
+ ```bash
497
+ export CHATTRS_PROJECT=alpha
498
+ chattrs projects # every project with agent and message counts
499
+ chattrs agents --all # include agents quiet for over 7 days
500
+ ```
501
+
502
+ ### One session per address
503
+
504
+ `hello` may carry a `session`, from `CHATTRS_SESSION`. The broker keeps an
505
+ in-memory record of which session holds each (project, address). A restart
506
+ clears it (ID-1).
507
+
508
+ - A `hello` from another session while the holder has a live connection
509
+ gets `address_in_use`. The message says how long ago the holder was last
510
+ active. The client does not retry. Wait, or use another address.
511
+ - The same session may open more connections. `watch`, `send`, and the
512
+ hooks all do.
513
+ - The address is free when the holder's last connection closes. A holder
514
+ that died without a close clears through TCP keepalive in about 1 minute.
515
+ Restart the worker with the same address and a new session. `chattrs env`
516
+ makes a new session on every run.
517
+ - An old client sends no session. It is never refused and never registered.
518
+ The broker only warns about a second live watch (CLI-15).
519
+ - An observer never registers and is never refused.
520
+ - A short-lived script sets no `CHATTRS_ADDRESS`. It takes no address and
521
+ fires no hooks. If it needs one, give it a unique address.
401
522
 
402
523
  ## Hooks (Claude Code and Codex)
403
524
 
404
- Hooks deliver unread messages between tool calls. Codex has no Monitor
405
- tool, so hooks are how a Codex worker hears a message. Meets HOOK-1.
525
+ Hooks deliver unread messages between tool calls (HOOK-1). Codex has no
526
+ Monitor tool, so hooks are how a Codex worker hears a message.
406
527
 
407
528
  ```bash
408
529
  chattrs hooks install [--agent claude|codex|all] [--project]
409
530
  chattrs hooks remove [--agent claude|codex|all] [--project]
410
531
  ```
411
532
 
412
- - User level (default): `~/.claude/settings.json` and
413
- `$CODEX_HOME/hooks.json` (else `~/.codex/hooks.json`). `--project`
414
- edits `.claude/settings.json` and `.codex/hooks.json` in the current
415
- directory. With `--agent all`, an agent whose config directory is
416
- missing is skipped; an explicit `--agent` creates the file.
417
- - Install merges in place: other hooks and key order stay. Own entries
418
- are the commands `chattrs hook <event> --agent claude|codex`. Install twice gives the same
419
- file. `remove` deletes only own entries. Invalid JSON exits 1 and
420
- writes nothing. A `.bak` copy is written once, when none exists. The
421
- file is written as 2-space pretty JSON with a trailing newline, so a
422
- file in that format is restored byte for byte by install then remove;
423
- another format keeps its content, not its layout.
424
- - After install, take the printed next step for each agent. Codex runs
425
- new hooks only after review: open Codex and run `/hooks` to trust
426
- them. Claude Code may ask you to review hooks edited outside it.
427
- Until then the hooks look installed but do not run.
533
+ - By default, install edits `~/.claude/settings.json` and
534
+ `$CODEX_HOME/hooks.json` (else `~/.codex/hooks.json`). `--project` edits
535
+ `.claude/settings.json` and `.codex/hooks.json` in the current directory.
536
+ With `--agent all`, an agent whose config directory is missing is
537
+ skipped. An explicit `--agent` creates the file.
538
+ - Install merges in place. Other hooks stay. The own entries are
539
+ `chattrs hook <event> --agent claude|codex`. Install twice gives the same
540
+ file. `remove` deletes only own entries. Invalid JSON exits 1 and writes
541
+ nothing. A `.bak` copy is written once.
542
+ - After install, follow the printed next step. Codex runs new hooks only
543
+ after review: open Codex and run `/hooks` to trust them. Claude Code may
544
+ ask you to review hooks edited outside it. Until then the hooks do not
545
+ run.
428
546
  - `chattrs` must be on the agent's `PATH`.
429
547
 
430
- What each event does (`chattrs hook <event>`):
431
-
432
548
  | Event | Effect |
433
549
  | ----- | ------ |
434
- | `session-start` | Fires on startup, clear, and compact, and behaves the same for all three (HOOK-2). Sets the state to idle. Tells the agent its address, its project when not `default`, its lead (`CHATTRS_LEAD`, when set), and to load the skill. Claude Code also gets the Monitor reminder (Codex has none; the Codex config passes `--agent codex`, and no flag means Claude). Then it adds the last 10 messages to and from the address, oldest first, in the `<agent-message>` wrapper. When `CHATTRS_LEAD` is unset or equals the address, it also lists up to 10 messages to the address that it has not replied to, most recent first. It reads the log and acks nothing. It gets about 800 ms and prints the address, lead, and skill lines even when the broker is unreachable. |
435
- | `user-prompt-submit`, `post-tool-use` | Adds unread messages as `additionalContext`, in the `<agent-message>` wrapper. `user-prompt-submit` also sets the state to working. |
436
- | `stop` | Sets the state to idle. When messages are unread, blocks the stop with them as the reason, and sets working again. Never blocks when `stop_hook_active` is true. |
437
-
438
- Each delivering event claims before it prints. It fetches the unread
439
- messages, acks them all, and prints only the ids the ack changed to read.
440
- Two hook runs that fire at once therefore split the messages and never
441
- print one twice. If the ack fails or times out, the run prints nothing.
442
- The cost: a message claimed but not printed (stdout closed) is not
550
+ | `session-start` | Fires on startup, clear, and compact (HOOK-2). Sets the state to idle. Tells the agent its address, its project (when not `default`), its lead (`CHATTRS_LEAD`), and to load the skill. Claude Code also gets the Monitor reminder. Then it adds the last 10 messages to and from the address, oldest first. When `CHATTRS_LEAD` is unset or equals the address, it also lists up to 10 messages the agent has not replied to. It acks nothing. It prints the address, lead, and skill lines even when the broker is down. |
551
+ | `user-prompt-submit`, `post-tool-use` | Add unread messages as `additionalContext`. `user-prompt-submit` also sets the state to working. |
552
+ | `stop` | Sets the state to idle. When messages are unread, it blocks the stop with them as the reason and sets working again. It never blocks when `stop_hook_active` is true. |
553
+
554
+ Each delivering event claims before it prints: it fetches unread messages,
555
+ acks them all, and prints only the ids that the ack changed. Two hook runs
556
+ at once split the messages and never print one twice. If the ack fails, the
557
+ run prints nothing. A message that was claimed but not printed is not
443
558
  redelivered.
444
559
 
445
- The hooks live in the user-level config, so they fire in every session.
446
- `chattrs hook` does nothing, with no output, unless `CHATTRS_ADDRESS` is
447
- set. It never starts a broker. It is best effort: connect plus exchange
448
- get about 300 ms, and any failure prints nothing and exits 0. A message
449
- that was not acked stays unread for the next command.
450
-
451
- Debugging aid: set `CHATTRS_HOOK_DEBUG=<file>` and each `chattrs hook` run
452
- appends one JSON line with `pid`, `ts_ms`, `event`, the raw stdin as
453
- `input`, and the ids it `fetched` and `emitted`. Use it to see which hook
454
- runs fire for one tool call and which ones deliver.
560
+ `chattrs hook` does nothing unless `CHATTRS_ADDRESS` is set. It never
561
+ starts a broker. It is best effort: it waits about 300 ms for the broker,
562
+ and any failure prints nothing and exits 0.
455
563
 
456
564
  ## Protocol
457
565
 
458
- One JSON object per line, `\n`-terminated. The `type` field disambiguates.
566
+ One JSON object per line, `\n`-terminated. The `type` field names the
567
+ frame. Protocol version is 1.
459
568
 
460
- Client → broker:
569
+ Client to broker:
461
570
 
462
571
  ```json
463
572
  {"type":"hello", "v":1, "address":"codex@box1", "token":"…", "tags":["os:linux","arch:x86_64","gpu"]}
573
+ {"type":"hello", "v":1, "address":"codex@box1", "project":"alpha", "session":"s1", "state":"working"}
574
+ {"type":"hello", "v":1, "address":"viewer@mac", "observer":true, "project":"*"}
464
575
  {"type":"send", "to":"opus@mac", "body":"hi", "reply_to":null, "topic":"release-26"}
465
576
  {"type":"send", "to":null, "body":"hi", "reply_to":null, "topic":"release-26"}
466
577
  {"type":"inbox"}
467
578
  {"type":"ack", "ids":[12, 13]}
468
579
  {"type":"watch"}
469
580
  {"type":"watch", "topics":["release-26"]}
470
- {"type":"hello", "v":1, "address":"codex@box1", "state":"working"}
471
- {"type":"hello", "v":1, "address":"viewer@mac", "observer":true}
472
- {"type":"hello", "v":1, "address":"viewer@mac", "observer":true, "project":"*"}
473
- {"type":"hello", "v":1, "address":"codex@box1", "project":"alpha"}
474
581
  {"type":"watch", "all":true}
475
582
  {"type":"wait", "reply_to":12}
476
583
  {"type":"agents"}
477
- {"type":"agents", "all":true}
478
- {"type":"agents", "projects":true}
584
+ {"type":"agents", "all":true, "projects":true}
479
585
  {"type":"log", "address":"codex@box1", "after":0, "limit":500}
586
+ {"type":"log", "address":"codex@box1", "tail":10}
480
587
  ```
481
588
 
482
- Broker → client:
589
+ Broker to client:
483
590
 
484
591
  ```json
485
592
  {"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha"}
@@ -490,221 +597,187 @@ Broker → client:
490
597
  {"type":"message", "id":13,"from":"opus@mac","to":"codex@box1",
491
598
  "body":"hi","ts":1763200000001,"reply_to":12,"topic":null,"project":"alpha"}
492
599
  {"type":"acked", "ids":[12, 13]}
493
- {"type":"agents", "agents":[{"project":"alpha","address":"codex@box1","last_seen":1763200000000,"online":true,"tags":["os:linux","gpu"],"state":"working","state_at":1763200000000}]}
494
- {"type":"log", "messages":[
495
- {"id":12,"from":"codex@box1","to":"opus@mac",
600
+ {"type":"agents", "agents":[{"project":"alpha","address":"codex@box1","last_seen":1763200000000,"online":true,"tags":["os:linux","gpu"],"state":"working","state_at":1763200000000}],
601
+ "projects":[{"project":"alpha","agents":2,"messages":14}]}
602
+ {"type":"log", "messages":[{"id":12,"from":"codex@box1","to":"opus@mac",
496
603
  "body":"hi","ts":1763200000000,"reply_to":null,"topic":null,"project":"alpha","acked_at":null}]}
497
- {"type":"agents", "agents":[…], "projects":[{"project":"alpha","agents":2,"messages":14}]}
498
604
  {"type":"error", "code":"empty_body", "message":"body is empty"}
499
605
  ```
500
606
 
501
- `hello` must be the first frame; anything else first gets `hello_required`
502
- and a closed connection. The broker sets the sender from the `hello`
503
- address; `send` carries no sender. A send to an unknown address succeeds —
504
- the inbox exists by name. When the broker has a token, every `hello` must
505
- carry it (loopback too) or the broker answers `bad_token` and closes the
506
- connection; without a token the broker ignores the field. One token covers
507
- the fleet, and addresses stay self-asserted: the token proves fleet
508
- membership, not which address is yours.
509
-
510
- A `send` with a `reply_to` and no `to` is a reply: the broker addresses it
511
- to the sender of that message, and rejects an unknown id with
512
- `unknown_message` or a message not sent to you with `not_recipient`. A
513
- `send` with both `to` and `reply_to` stays valid; the broker only checks
514
- that the id exists. A `send` with a `topic` and no `to` is an
515
- announcement to that room: the wire message carries `"to":null`, it is
516
- stored with no owning inbox, and a `send` with no `to` and no `topic` is
517
- rejected with `bad_address`. A direct message with a topic stays direct:
518
- its topic is only a label, and topic watchers never receive it.
519
-
520
- `hello` may carry an optional `project`, which the client reads from
521
- `CHATTRS_PROJECT`. It is validated like a topic name; an invalid name gets
522
- `bad_project`. Without it the project is `default`, and `welcome` echoes the
523
- effective `project` (an older broker omits it). Every frame is scoped to the
524
- connection's project: `send` (`to` is always in the sender's project),
525
- `inbox`, `wait`, `ack`, `agents`, `log`, `watch` with and without topics,
526
- topic backlogs, `known`, and the online count, which is keyed by project and
527
- address. Message and agent JSON carry `project`; a frame from an older
528
- broker without it reads as `default`. Only an observer may send
529
- `"project":"*"`; any other `hello` with `*` gets `bad_project`. A `*` observer's
530
- `watch` with `all`, its `log`, and its `agents` span every project, and each
531
- message and agent row carries its `project`. An observer with a named
532
- project sees only that project. `agents` leaves out an agent that is
533
- offline, last seen over 7 days ago, and has sent or received nothing for 7
534
- days, unless the request sets `"all":true`; nothing is deleted. With
535
- `"projects":true`, the `agents` answer adds `projects`, the agent and message
536
- count of each project the connection can see (one for a named project, every
537
- project for `*`); `chattrs projects` is that request from a `*` observer.
538
-
539
- `inbox` returns every message for the `hello` address with no ack yet, in
540
- id order. `ack` marks the listed ids read when they belong to that address
541
- and are unread, and `acked` lists the ids that changed; other ids are
542
- ignored. Except for `watch`, the broker never pushes messages: the client
543
- asks. Every accepted `hello` records the address with the broker clock, and
544
- the broker records it again when that connection closes. `agents` returns
545
- all recorded addresses sorted by address; an address that only received
546
- messages and never connected is not listed. `hello` may carry an optional
547
- `tags` list (at most 32 tags of 64 bytes each, else `bad_tags`). The client
548
- always sends `os:<os>` and `arch:<arch>`, plus the comma-separated entries of
549
- `CHATTRS_TAGS` (for example `CHATTRS_TAGS=gpu:4090,fast`). The broker keeps
550
- the tags of the latest `hello` that sent any, and `agents` shows them after
551
- the last-seen time; `agents --json` always has a `tags` array. Tags come from the latest hello. Set `CHATTRS_TAGS` in the worker's launch environment. A chattrs command run from another shell without it replaces the agent's tags with `os` and `arch`. Each agent
552
- also has `online`: `true` while the address has a live inbox `watch`
553
- connection (topic watches do not count), else `false`. The broker counts
554
- this in memory and never stores it; an older broker omits it, which reads as
555
- `false`. `agents` text shows `online` in place of the last-seen time.
556
- `hello` may also carry an optional `state`: `working`, `idle`, or `waiting`
557
- (else `bad_state`). The broker stores the state and the time it was set
558
- (`state_at`, ms on the broker clock) when a `hello` carries one; a `hello`
559
- without a state keeps both. An observer `hello` with a state gets
560
- `observer_read_only`. `agents` text shows the state after the online or
561
- last-seen column and before the tags, and shows nothing when the agent never
562
- reported one; `agents --json` always has `state` and `state_at`, `null`
563
- when never set. The broker never expires a state. A client shows a state
564
- older than 15 minutes as `unknown`; `agents` text does. `chattrs status
565
- <state>` sends such a `hello`.
607
+ `projects` appears only when the request sets `"projects":true`.
608
+
609
+ **Hello.** `hello` must come first, or the broker answers `hello_required`
610
+ and closes. The broker takes the sender from the `hello` address. A `send`
611
+ carries no sender. When the broker has a token or table, every `hello`
612
+ carries a token, loopback too. Optional `hello` fields:
613
+
614
+ - `project` (from `CHATTRS_PROJECT`): validated like a topic. Default is
615
+ `default`. `welcome` echoes it. Only an observer may use `*`.
616
+ - `session`: see [One session per address](#one-session-per-address).
617
+ - `tags`: at most 32 tags of 64 bytes. The client sends `os:<os>`,
618
+ `arch:<arch>`, and the `CHATTRS_TAGS` entries. The broker keeps the tags
619
+ of the latest `hello` that sent any.
620
+ - `state`: `working`, `idle`, or `waiting`. The broker stores it with
621
+ `state_at` (ms, broker clock). A `hello` without a state keeps the old
622
+ one. The broker never expires a state. A client shows a state older than
623
+ 15 minutes as `unknown` (MON-4). `chattrs status` sends such a `hello`.
624
+ - `observer`: see [Monitoring](#monitoring-api-observer).
625
+
566
626
  `welcome` may carry `"watching":true` when the address already has a live
567
- inbox `watch` at `hello` time; it is omitted otherwise, and from an older
568
- broker. The `watch` command then warns once per connect on stderr and keeps
569
- watching; other commands ignore it. The `inbox` command prints each message, flushes stdout, then acks,
570
- so a crash between print and ack redelivers the message on the next run —
571
- delivery is at least once, and the id tells duplicates apart.
627
+ inbox `watch`. The `watch` command then warns once on stderr and keeps
628
+ going.
629
+
630
+ **Send.** A send to an unknown address succeeds, and the inbox exists by
631
+ name (MSG-8). A `send` with `reply_to` and no `to` is a reply: the broker
632
+ addresses it to the sender of that message. A reply without a `topic`
633
+ stores the topic of the message it answers. A `send` with a `topic` and no
634
+ `to` is an announcement: it has `"to":null` and no owning inbox. No `to`
635
+ and no `topic` gets `bad_address`. A direct message with a topic stays
636
+ direct: topic watchers never see it.
637
+
638
+ **Scope.** Every frame is scoped to the connection's project: `send`,
639
+ `inbox`, `wait`, `ack`, `agents`, `log`, `watch`, topic backlogs, `known`,
640
+ and the online count. Message and agent rows carry `project`. A frame from
641
+ an older broker without it reads as `default`.
642
+
643
+ **Inbox and ack.** `inbox` returns every unread message for the `hello`
644
+ address, in id order. `ack` marks the listed ids read when they belong to
645
+ that address. `acked` lists the ids that changed. Delivery is at least
646
+ once: a crash between print and ack prints the message again. The id
647
+ tells duplicates apart.
648
+
649
+ **Agents.** Every accepted `hello` records the address with the broker
650
+ clock, and the broker records it again on close. `agents` lists the
651
+ recorded addresses of the project, sorted by address. An address that only
652
+ received messages is not listed. `online` is true while the address has a
653
+ live inbox `watch` (topic watches do not count). The broker counts it in
654
+ memory. `agents` leaves out an agent that is offline, last seen over 7 days
655
+ ago, with no traffic in 7 days, unless the request sets `"all":true`.
656
+ Nothing is deleted. With `"projects":true`, the answer adds the counts of
657
+ every project the connection can see.
658
+
659
+ **Watch.** The broker subscribes the connection, sends every unread message
660
+ in id order, then each new one. It skips ids it already sent. A connection
661
+ that falls behind is closed. The `watch` command prints each message as one
662
+ JSON line, acks it on the same connection, and reconnects with backoff from
663
+ 1 s to 30 s. Two watchers on one address both get every message.
664
+
665
+ With `topics`, `watch` subscribes to those rooms instead of the inbox. The
666
+ broker sends each room's latest 500 announcements in id order, then each
667
+ new one. The client never acks them. A reconnect replays the backlog, so
668
+ an announcement can arrive twice. There is no join or leave: closing the
669
+ watcher ends the subscription.
670
+
671
+ **Wait and ask.** `wait` sends the lowest-id message to the `hello` address
672
+ with that `reply_to`, at once or when it arrives. `ask` sends its question,
673
+ parks a `wait`, prints the reply, acks it, and exits 0, all on one
674
+ connection. On a timeout it writes `timeout: no reply to <id>` to stderr
675
+ and exits 2 (`{"type":"timeout","id":12}` with `--json`). The late reply
676
+ stays unread. After a drop, `ask` resends only the `wait`, never the
677
+ question.
678
+
679
+ **Log.** `log` returns messages with id above `after`, in id order, at most
680
+ `limit` (cap 500), with `acked_at` set for read messages. With `address`,
681
+ only that sender or recipient. It never acks. The `log` command pages until
682
+ a page has fewer than 500 rows. With `tail` N, `log` returns the newest N
683
+ rows in one round trip, still in id order, and ignores `limit`. An old
684
+ broker ignores `tail`, and the client keeps the last N rows it got.
572
685
 
573
686
  ### Monitoring API (observer)
574
687
 
575
- A monitor, such as a tray, uses only the wire protocol:
688
+ A monitor, such as the tray, uses only the wire protocol (MON-3):
576
689
 
577
690
  1. `hello` with `"observer":true`. The broker never records the address,
578
- never lists it in `agents`, and never counts it as online or `watching`.
579
- It stores no tags from an observer `hello`. The token check is the same.
580
- 2. The `welcome` echoes `"observer":true`. A broker without observer support
581
- omits it; the client must then fall back to polling `log`.
691
+ lists it in `agents`, or counts it as online or `watching`. It stores no
692
+ tags from it. The token check is the same. A `"project":"*"` observer
693
+ sees every project. Otherwise it sees its own project.
694
+ 2. `welcome` echoes `"observer":true`. A broker without observer support
695
+ omits it. The client then polls `log`.
582
696
  3. `watch` with `"all":true` streams each new message, direct and
583
- announcements, as `message` frames. It sends no backlog and acks nothing.
584
- `all` on a connection that did not say `observer` gets `not_observer`.
697
+ announcements, as `message` frames. It sends no backlog and acks nothing
698
+ (MON-1). `all` without an observer hello gets `not_observer`.
585
699
  4. `agents` gives presence, tags, and state. `log` gives history.
586
- 5. `"project":"*"` on the observer `hello` streams and lists every project;
587
- without it the observer sees only its own project.
588
700
 
589
- An observer connection is read-only: `send`, `ack`, `wait`, and `inbox` get
590
- `observer_read_only`. A slow observer that falls behind is disconnected, so
591
- it never delays a sender. To catch up after a connect or a drop, start
592
- `watch` with `all` first and buffer what it streams, then read
593
- `log` with `after` set to the last id you hold, and drop duplicates by
594
- message id.
701
+ An observer is read-only: `send`, `ack`, `wait`, and `inbox` get
702
+ `observer_read_only`, and so does a `hello` with a `state`. A slow
703
+ observer is disconnected, so it never delays a sender. To catch up, start
704
+ `watch` with `all` first and buffer what it streams. Then read `log` with
705
+ `after` set to the last id you hold. Drop duplicates by id.
595
706
 
596
707
  #### Viewer contract
597
708
 
598
- Viewers are separate programs that use this contract. The `chattrs` binary
599
- stays CLI only, with no TUI or GUI. The swarm needs nothing from any viewer.
600
-
601
- - A read-only viewer connects as an observer: `hello` with
602
- `"observer":true`, then check the `welcome` echo. Start `watch` with
603
- `"all":true` first, then read `log` after the last id you hold, and drop
604
- duplicates by id. Use `agents` for presence, tags, and state. An observer
605
- is read-only.
606
- - Messages and agent rows carry `project`. A viewer that observes `*`
607
- groups by it. Until signed tokens land, the shared token reaches every
608
- project.
609
- - An interactive viewer, a GUI or TUI that sends or replies, connects as a
610
- normal agent with its own address, such as `operator@mac`, and uses the
611
- normal frames.
612
- - Health (MON-5) is not on the wire. A viewer computes it from the `agents`
613
- row and its own clock, the same way `chattrs agents` does. Activity is the
614
- later of `last_seen` and `state_at`. Check in this order:
615
- `gone` when not `online` and `last_seen` is more than 1 h ago;
616
- `stalled` when `state` is `working` and activity is 10 min or more ago;
617
- `healthy` when `online` and activity is under 10 min ago; else no label.
618
- Hooks say `hello` on every tool call, so `last_seen` is an activity
619
- heartbeat. There is no ping probe, and no lease rule yet.
709
+ Viewers are separate programs. The `chattrs` binary stays CLI only.
710
+
711
+ - A read-only viewer connects as an observer and follows the catch-up flow
712
+ above. Use `agents` for presence, tags, and state.
713
+ - A viewer that observes `*` groups rows by `project`. In legacy mode the
714
+ shared token reaches every project. With a token table, only an entry
715
+ with `project = "*"` does.
716
+ - With a token table, a message also carries `from_role` (`lead` or
717
+ `agent`). It is absent without a table and on older rows. A viewer may
718
+ show it next to `from`. It proves no more than the token table proves.
719
+ - An interactive viewer, one that sends or replies, connects as a normal
720
+ agent with its own address, such as `operator@mac`.
721
+ - Health (MON-5) is not on the wire. A viewer computes it from the
722
+ `agents` row and its own clock, as `chattrs agents` does. Activity is the
723
+ later of `last_seen` and `state_at`. Check in this order: `gone` when not
724
+ `online` and `last_seen` is over 1 h ago; `stalled` when `state` is
725
+ `working` and activity is 10 min or more ago; `healthy` when `online` and
726
+ activity is under 10 min ago; else no label. Hooks say `hello` on every
727
+ tool call, so `last_seen` works as an activity heartbeat. There is no
728
+ ping.
620
729
  - A viewer ignores unknown fields and unknown frame types.
621
- - The observer frames and the `agents` JSON shape are stable. They change
622
- only by adding fields.
623
-
624
- On `watch`, the broker first subscribes the connection to its one
625
- broadcast, then sends every unread message in id order, then each new
626
- message the broadcast carries for that connection. It tracks the highest
627
- id sent on the connection and skips ids at or below it, so the hand-over
628
- does not duplicate. A connection that falls behind the broadcast is
629
- closed; the client reconnects and the broker replays from the store.
630
- Two watchers on one address both get every message. The `watch` command
631
- prints each message as one JSON line, flushes stdout, then acks it on
632
- the same connection — always JSON, nothing else on stdout — and never
633
- exits by itself. A watching connection still answers other frames, so
634
- its `ack` needs no second connection. When the connection drops it
635
- reconnects with backoff from 1 s to 30 s, logging to stderr only.
636
-
637
- With `topics`, `watch` subscribes to those rooms instead of the inbox:
638
- on subscribe the broker sends each room's most recent 500 announcements
639
- merged in id order, then each new announcement as it arrives, skipping
640
- ids at or below the highest id already sent so the backlog-to-live
641
- hand-over does not duplicate. The client prints each announcement as one
642
- JSON `message` line with `"untrusted":true` and never acks it. A
643
- reconnect replays the backlog window, so a listener may see an
644
- announcement twice across a reconnect; the id tells duplicates apart.
645
- Closing the watcher ends the subscription: there is no join or leave,
646
- and the broker tracks no listener list.
647
-
648
- On `wait`, the broker subscribes the connection, then sends the
649
- lowest-id message to the `hello` address with that `reply_to`, whether
650
- it is acked or not — at once when one exists, else when one arrives.
651
- One `wait` gets one message, and the connection keeps reading frames
652
- while it waits. The reply also reaches live `watch` connections, so an
653
- agent running both sees it twice. The `ask` command sends its question,
654
- parks a `wait`, and on the reply prints it wrapped as `<agent-message>`
655
- text (or one JSON `message` line with `"untrusted":true` when
656
- `--json`), flushes stdout, acks it, and exits 0 — all on one connection.
657
- On a timeout it closes the connection, writes `timeout: no reply to
658
- <id>` to stderr, exits 2 (and prints `{"type":"timeout","id":12}` with
659
- `--json`); the late reply stays unread. A dropped connection reconnects
660
- with the `watch` backoff and resends only the `wait`, never the
661
- question, and the reply is acked on the connection that received it.
662
-
663
- `log` returns messages with id above `after`, in id order, at most
664
- `limit` (capped at 500), with `acked_at` set for read messages and null
665
- for unread ones. With `address`, only messages where it is the sender or
666
- the recipient are returned; without it, the full history is. `log` reads
667
- only: it never acks. The `log` command pages with `after` until a page
668
- holds fewer than 500 rows, so its output is the full history.
669
-
670
- A `send` with a `reply_to` and no `topic` stores the topic of the
671
- message it answers; an explicit `topic` always wins. An invalid slug is
672
- rejected with `bad_topic`.
673
-
674
- Error codes: `bad_frame`, `hello_required`, `bad_version` (v ≠ 1),
675
- `bad_address`, `bad_token`, `bad_tags`, `bad_project`, `bad_topic`, `empty_body`, `too_large`,
676
- `unknown_message`, `not_recipient`. After `hello`, an error does not
677
- close the connection, except `bad_token`, which always closes it.
678
-
679
- Limits: an address is `user@host` (`[A-Za-z0-9._-]` each side, 128 bytes
680
- max). A body is 1 byte to 64 KiB. A topic is 1-64 bytes of lowercase
681
- letters, digits, and hyphens, never starting or ending with a hyphen.
682
- An inbound line over 128 KiB is rejected with `too_large`.
730
+ - The observer frames and the `agents` JSON shape change only by adding
731
+ fields.
732
+
733
+ ### Errors and limits
734
+
735
+ Error codes: `bad_frame`, `hello_required`, `bad_version` (v is not 1),
736
+ `bad_address`, `bad_token`, `forbidden`, `bad_tags`, `bad_project`,
737
+ `bad_session`, `address_in_use`, `bad_state`, `observer_read_only`,
738
+ `not_observer`, `bad_topic`, `empty_body`, `too_large`, `unknown_message`,
739
+ `not_recipient`, `internal`. After `hello`, an error does not close the
740
+ connection. `bad_token` always does.
741
+
742
+ An address is `user@host` (`[A-Za-z0-9._-]` each side, 128 bytes max). A
743
+ body is 1 byte to 64 KiB. A topic is 1 to 64 bytes of lowercase letters,
744
+ digits, and hyphens, and does not start or end with a hyphen. A line over
745
+ 128 KiB gets `too_large`.
746
+
747
+ ## Compatibility
748
+
749
+ The protocol is v1. New fields are optional, so old clients keep working.
750
+ Upgrade the broker first, then the clients. Check `chattrs --version` on
751
+ each host. Projects, the token table, and sessions need a broker of the
752
+ matching version. An older broker ignores them.
683
753
 
684
754
  ## Design
685
755
 
686
- - **Durable before anything else.** The broker commits each message to
687
- SQLite before it confirms the send, so a restart loses nothing. The broker
688
- never deletes a message.
689
- - **Addresses, not accounts.** An agent is whoever its `hello` says it is.
690
- The broker stays on loopback unless a token guards a wider bind, and one
691
- fleet token admits every address.
756
+ - **Durable first.** The broker commits each message to SQLite before it
757
+ confirms the send. A restart loses nothing. The broker never deletes a
758
+ message (MSG-1).
759
+ - **Addresses, not accounts.** An agent is whoever its `hello` says, unless
760
+ a token table limits the token.
692
761
  - **Small and boring.** One SQLite file, line-JSON over TCP, no framework.
693
762
 
694
763
  ## Repository
695
764
 
696
- - `src/main.rs` — thin entry, dispatch.
697
- - `src/autostart.rs` — on-demand broker start, pidfile, `stop`.
698
- - `src/cli.rs` — argument parsing only.
699
- - `src/model.rs` — wire types and their serde shapes.
765
+ - `src/main.rs` — entry and dispatch.
766
+ - `src/cli.rs` — argument parsing.
767
+ - `src/config.rs` — config files.
768
+ - `src/model.rs` — wire types.
700
769
  - `src/protocol.rs` — line-JSON framing.
701
770
  - `src/store.rs` — SQLite storage.
702
- - `src/server.rs` — the broker.
771
+ - `src/server.rs`, `src/server/` — the broker.
772
+ - `src/tokens.rs` — token table.
703
773
  - `src/client.rs` — one connection per command.
704
- - `src/skill.rs` — embedded agent skill text printed by `chattrs skill`.
774
+ - `src/autostart.rs` — on-demand broker start, `stop`.
775
+ - `src/hook.rs`, `src/hook_install.rs` — hooks.
776
+ - `src/output.rs`, `src/skill.rs` — printing and the embedded skill.
777
+ - `tray/` — the macOS menu bar app.
705
778
 
706
- See `docs/code-style.md` for conventions and `docs/planning.md` for the
707
- roadmap.
779
+ See [docs/mission.md](docs/mission.md), [docs/requirements.md](docs/requirements.md),
780
+ [docs/planning.md](docs/planning.md), and [docs/code-style.md](docs/code-style.md).
708
781
 
709
782
  ## License
710
783