chattrs 0.5.0 → 0.6.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
@@ -25,55 +25,147 @@ over TCP, so a script in any language can join too.
25
25
 
26
26
  ## Get running
27
27
 
28
+ chattrs never starts agents. You start them. `chattrs env` sets the
29
+ address and the session in the launch line.
30
+
28
31
  ### Solo, one machine
29
32
 
30
- Install chattrs, then set up the agents once.
33
+ Three steps.
31
34
 
32
- ```bash
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
36
- ```
35
+ 1. Install chattrs. On macOS: `brew install bolu-atx/tap/chattrs`. For
36
+ npm or cargo, see [Install](#install).
37
+ 2. Set up the agents once:
37
38
 
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.
39
+ ```bash
40
+ chattrs setup
41
+ ```
41
42
 
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.
43
+ `setup` finds Claude Code and Codex. For each one it installs the hooks
44
+ and the skill. It writes `~/.config/chattrs/config.toml` only when none
45
+ exists. It is safe to run again. Then follow the printed trust steps:
46
+ open Codex once and run `/hooks` to trust the new hooks. Claude Code may
47
+ ask you to review the hooks.
48
+ 3. Start a lead and a worker in two terminals:
44
49
 
45
- ```bash
46
- # Terminal 1
47
- eval "$(chattrs env --as lead@mac)" && claude
50
+ ```bash
51
+ # Terminal 1
52
+ eval "$(chattrs env --as lead@mac)" && claude
48
53
 
49
- # Terminal 2
50
- eval "$(chattrs env --as w1@mac --lead lead@mac)" && codex
51
- ```
54
+ # Terminal 2
55
+ eval "$(chattrs env --as w1@mac --lead lead@mac)" && codex
56
+ ```
52
57
 
53
58
  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`.
59
+ hook tells each agent its address and its lead, and to load the skill.
60
+ Ask the lead to send w1 a task. Run `chattrs agents` to see both agents.
61
+ An agent shows `online` only while it runs `chattrs watch`. Hooks deliver
62
+ messages between tool calls. In Claude Code, the agent runs `chattrs
63
+ watch` under Monitor, so a message wakes it.
60
64
 
61
65
  ### Swarm, several machines
62
66
 
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)).
67
+ Five steps. Use a broker host that is always on. A laptop sleeps, and the
68
+ swarm stops. Install and run `chattrs setup` on every host first, as in
69
+ the solo path.
70
+
71
+ 1. On the broker host, issue tokens and write the service unit:
72
+
73
+ ```bash
74
+ chattrs setup --broker --hosts mac,bobox --bind 100.64.0.1 --enable
75
+ ```
76
+
77
+ `--hosts` lists the agent hosts. `--bind` is the tailnet or LAN IP. It
78
+ defaults to the Tailscale IPv4. It never takes `0.0.0.0` or `::`.
79
+ `--enable` starts the service. The command prints one join string for
80
+ each token.
81
+ 2. Copy each host's join string to that host, over a private channel. A
82
+ join string holds a token. Treat it like a password. The broker never
83
+ stores it.
84
+ 3. On each host, run `setup --join` and paste the join strings on stdin.
85
+ End with Ctrl-D. This keeps them out of shell history:
86
+
87
+ ```bash
88
+ chattrs setup --join -
89
+ ```
90
+
91
+ It writes a token file (mode 0600) and one `[tokens]` entry in
92
+ `~/.config/chattrs/config.toml`, and it sets `server`. A host that runs
93
+ agents next to the broker needs this step too. The lead host needs
94
+ the lead's join string as well.
95
+ 4. On each host, check the setup:
96
+
97
+ ```bash
98
+ chattrs doctor --as w1@bobox
99
+ ```
100
+
101
+ Each check prints `ok` or `FAIL` with a fix hint. The command exits 1
102
+ on any failure.
103
+ 5. Launch every agent with its own address:
104
+
105
+ ```bash
106
+ eval "$(chattrs env --as lead@mac)" && claude
107
+ eval "$(chattrs env --as w1@bobox --lead lead@mac)" && codex
108
+ ```
109
+
110
+ `env --as` exports the address, a new session id, and the server. It does
111
+ not print the token. Each command then reads the token from the `[tokens]`
112
+ entry that matches the address. To set the project for all hosts, commit a
113
+ `.chattrs.toml` in the repo ([Environment and config](#environment-and-config)).
114
+
115
+ ### Several hosts: `setup --broker` and `setup --join` (SETUP-2)
116
+
117
+ Reference for steps 1 to 3 above.
118
+
119
+ ```bash
120
+ chattrs setup --broker --hosts <a,b> [--lead lead@mac] [--projects p1,p2] \
121
+ [--bind <ip>] [--port 4646] [--enable]
122
+ ```
123
+
124
+ It writes `~/.config/chattrs/tokens.toml` (mode 0600) and a systemd user unit
125
+ (`~/.config/systemd/user/chattrs.service`) or a launchd plist
126
+ (`~/Library/LaunchAgents/com.chattrs.broker.plist`). It never overwrites
127
+ either file. It prints the command that starts the service; `--enable` runs
128
+ it. It issues one agent token per host (`*@<host>`), one lead token, and one
129
+ observer token (`tray@*`, all projects). Then it prints one join string for
130
+ each, `chattrs://<token>@<ip>:<port>?as=<pattern>`. The pattern is
131
+ percent-encoded.
132
+
133
+ `setup --join` also takes a string as an argument. Quote it, but it then
134
+ stays in shell history:
135
+
136
+ ```bash
137
+ chattrs setup --join 'chattrs://TOKEN@100.64.0.1:4646?as=lead%40mac'
138
+ ```
139
+
140
+ `--join` is repeatable, and stdin can carry one string per line. A string
141
+ without `?as=` needs `--as <pattern>` (one string only). Each string writes
142
+ `~/.config/chattrs/<name>.token` (mode 0600). The name is the pattern with
143
+ `@` as `-` and `*` as `any`: `lead@mac` gives `lead-mac.token`,
144
+ `*@bobox` gives `any-bobox.token`. The command sets `server` when it is
145
+ missing, and it refuses a different `server`. It keeps all other lines. It
146
+ refuses a pattern that already has an entry or a file; `--force` replaces
147
+ them. Then it runs the plain `setup`. The project is not in the join
148
+ string; it comes from `.chattrs.toml`, else `default`.
149
+
150
+ ### Check a host: `doctor` (SETUP-3)
151
+
152
+ Reference for step 4 above. Run `chattrs doctor` in the environment of an
153
+ agent (with `CHATTRS_ADDRESS` set, or pass `--as`). It prints one line per
154
+ check, `ok <check>: ...` or `FAIL <check>: ... <fix hint>`, and exits 1 on
155
+ any failure. It checks the config files, the token file each identity uses
156
+ (mode 0600), that the broker accepts a connection, that the broker accepts
157
+ the token for the project and address, the protocol version, the hooks, and
158
+ the skill text. It never prints a token. It writes no file and reads no
159
+ message. The token check sends one normal `hello` as the current address,
160
+ with `CHATTRS_SESSION`, so the broker logs no rejection. It shows the project
161
+ and the broker version from the `welcome`. The `hello` updates the last-seen
162
+ of the current address, so that address looks active to health for a moment.
163
+ This is known and not fixed. Other `[tokens]` identities are listed and not
164
+ probed. Without a current address, doctor checks only that the broker accepts
165
+ a connection and prints a warning. Without `CHATTRS_SESSION`, doctor says
166
+ `hello` without a session and prints a note: use `chattrs env`. A `tray@`
167
+ identity says an observer `hello`. Codex hook trust cannot be detected, so
168
+ doctor always ends with a reminder to trust the hooks in `/hooks` in Codex.
77
169
 
78
170
  ## Install
79
171
 
@@ -90,6 +182,8 @@ build (DIST-1).
90
182
 
91
183
  ## Quick start
92
184
 
185
+ This is the raw CLI on one machine, with no agent. For agents, see [Get running](#get-running).
186
+
93
187
  One machine, no broker terminal. The first command starts a loopback broker
94
188
  on `127.0.0.1:4646`. The broker logs to `chattrs.log` and writes its pid to
95
189
  `chattrs.pid`, both next to the DB. `chattrs stop` ends it.
@@ -127,7 +221,7 @@ that holds `</agent-message` is escaped, so it cannot close the wrapper.
127
221
 
128
222
  ## Commands
129
223
 
130
- Every command except `serve`, `stop`, `skill`, `env`, and `hooks` takes the
224
+ Every command except `serve`, `stop`, `skill`, `env`, `setup`, `doctor`, and `hooks` takes the
131
225
  [common flags](#environment-and-config). Every one except `status`, `projects`,
132
226
  `hook`, and `watch` first prints unread messages, then its own output, and
133
227
  acks them (MSG-5). Announcements never reach an inbox.
@@ -146,6 +240,8 @@ acks them (MSG-5). Announcements never reach an inbox.
146
240
  | `projects [--json]` | List every project with its agent and message counts. Read-only. |
147
241
  | `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
242
  | `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`. |
243
+ | `setup` | Install the hooks and the skill for each agent found (Claude Code, Codex). Write a starter `config.toml` only if missing. Safe to run again. `setup --broker --hosts a,b [...]` prepares a broker host; `setup --join STRING\|-` stores join-string tokens. See [Several hosts](#several-hosts-setup---broker-and-setup---join-setup-2). |
244
+ | `doctor [--as ADDR] [--server S]` | Check config, token files, broker, token, protocol, hooks, and skill. One `ok` or `FAIL` line each; exit 1 on any failure. Read-only. See [Check a host](#check-a-host-doctor-setup-3). |
149
245
  | `hooks install\|remove [--agent claude\|codex\|all] [--project]` | Edit the hook entries in the agent configs. See [Hooks](#hooks-claude-code-and-codex). |
150
246
  | `hook EVENT` | Run as a hook. Reads hook JSON on stdin. Not for direct use. |
151
247
  | `skill` | Print the bundled agent skill. Needs no connection or address. |
@@ -178,6 +274,24 @@ is an error that names the file and line. The repo file holds no secrets: a
178
274
  that holds only the token. On unix it must have mode 0600 or tighter. The
179
275
  token applies when neither `CHATTRS_TOKEN` nor `--token` is set.
180
276
 
277
+ One host can hold several identities (SETUP-4). A `[tokens]` table in the
278
+ user config maps an address or a glob to its own token file:
279
+
280
+ ```toml
281
+ token_file = "/home/me/.config/chattrs/token" # fallback
282
+ [tokens]
283
+ "lead@mac" = "/home/me/.config/chattrs/lead-token"
284
+ "*@mac" = "/home/me/.config/chattrs/mac-token"
285
+ ```
286
+
287
+ The token for an address comes from the first of these that applies:
288
+ `CHATTRS_TOKEN` or `--token`; the `[tokens]` entry that matches the address
289
+ (an exact address beats a glob, and among globs the longest pattern wins);
290
+ the plain `token_file`. The address is `--as`, `--address`, or `--agent`,
291
+ then `CHATTRS_ADDRESS`, then `CHATTRS_AGENT`. `chattrs env --as ADDR
292
+ --with-token` prints the token for ADDR. The table is only in the user
293
+ config, never in `.chattrs.toml`.
294
+
181
295
  ```toml
182
296
  # ~/.config/chattrs/config.toml
183
297
  server = "10.0.0.5:4646"
@@ -214,13 +328,15 @@ Tags come from the latest `hello`. A command run from another shell without
214
328
  ## Teach workers the skill
215
329
 
216
330
  `chattrs skill` prints the worker skill (`skills/chattrs/SKILL.md`).
331
+ `chattrs setup` installs it for Claude Code and Codex. To install it by
332
+ hand:
217
333
 
218
334
  ```bash
219
335
  mkdir -p ~/.claude/skills/chattrs && chattrs skill > ~/.claude/skills/chattrs/SKILL.md
220
336
  ```
221
337
 
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.
338
+ For pi, pass that directory with `--skill`. Muse has no skill directory:
339
+ the lead puts `$(chattrs skill)` in the worker's prompt.
224
340
 
225
341
  Give each worker a unique address. Two agents on one address share an
226
342
  inbox. There is no default agent name.
@@ -248,15 +364,18 @@ holder every project and every address. Use it for a quick test only.
248
364
  ### Keep the database
249
365
 
250
366
  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:
367
+ message, so the database is the swarm's history. Back it up with
368
+ `chattrs backup`, never with `cp` on a live database. It works while the
369
+ broker runs and refuses to replace a file unless you pass `--force`:
253
370
 
254
371
  ```bash
255
- sqlite3 <db> ".backup <file>"
372
+ chattrs backup <file> [--db <db>] [--force]
256
373
  ```
257
374
 
258
375
  ### Run the broker as a service
259
376
 
377
+ `chattrs setup --broker` writes these units for you ([Get running](#get-running)). Use this section to write them by hand.
378
+
260
379
  Linux: put a `systemd --user` unit in
261
380
  `~/.config/systemd/user/chattrs.service`.
262
381
 
@@ -315,6 +434,8 @@ for an unattended Mac.
315
434
 
316
435
  ### Set client hosts
317
436
 
437
+ `chattrs setup --join` does this for you ([Get running](#get-running)). Use this section to edit the config by hand.
438
+
318
439
  On every client host, set the broker address and the token file in the user
319
440
  config (see [Environment and config](#environment-and-config)):
320
441
 
@@ -455,12 +576,14 @@ Rules:
455
576
 
456
577
  #### Turning on per-host tokens
457
578
 
579
+ This is for a swarm that already runs on the shared token. A new swarm uses `chattrs setup --broker` instead.
580
+
458
581
  Once a tokens file exists, the broker refuses the shared token. Switching
459
582
  everything at once breaks every client at the same moment. Use two phases.
460
583
 
461
584
  Phase 1: a plain upgrade.
462
585
 
463
- 1. Back up the database: `sqlite3 <db> ".backup <file>"`.
586
+ 1. Back up the database: `chattrs backup <file> --db <db>`.
464
587
  2. Upgrade the broker. Start it with no tokens file. Legacy mode stays on.
465
588
  3. Check that workers and viewers still connect.
466
589
 
@@ -589,7 +712,7 @@ Client to broker:
589
712
  Broker to client:
590
713
 
591
714
  ```json
592
- {"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha"}
715
+ {"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha", "version":"0.6.0"}
593
716
  {"type":"sent", "id":12} // optional "known":false: `to` never said hello
594
717
  {"type":"inbox", "messages":[
595
718
  {"id":12,"from":"codex@box1","to":"opus@mac",
@@ -623,6 +746,9 @@ carries a token, loopback too. Optional `hello` fields:
623
746
  15 minutes as `unknown` (MON-4). `chattrs status` sends such a `hello`.
624
747
  - `observer`: see [Monitoring](#monitoring-api-observer).
625
748
 
749
+ `welcome` carries `"version"`, the broker's crate version. It is optional:
750
+ an older broker omits it, and an older client ignores it. `doctor` shows it.
751
+
626
752
  `welcome` may carry `"watching":true` when the address already has a live
627
753
  inbox `watch`. The `watch` command then warns once on stderr and keeps
628
754
  going.
@@ -19,7 +19,7 @@
19
19
  "hasInstallScript": true,
20
20
  "license": "MIT",
21
21
  "name": "chattrs",
22
- "version": "0.5.0"
22
+ "version": "0.6.0"
23
23
  },
24
24
  "node_modules/detect-libc": {
25
25
  "engines": {
@@ -48,5 +48,5 @@
48
48
  }
49
49
  },
50
50
  "requires": true,
51
- "version": "0.5.0"
51
+ "version": "0.6.0"
52
52
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "artifactDownloadUrls": [
3
- "https://github.com/bolu-atx/chattrs/releases/download/v0.5.0"
3
+ "https://github.com/bolu-atx/chattrs/releases/download/v0.6.0"
4
4
  ],
5
5
  "bin": {
6
6
  "chattrs": "run-chattrs.js"
@@ -79,7 +79,7 @@
79
79
  "zipExt": ".tar.xz"
80
80
  }
81
81
  },
82
- "version": "0.5.0",
82
+ "version": "0.6.0",
83
83
  "volta": {
84
84
  "node": "18.14.1",
85
85
  "npm": "9.5.0"