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 +171 -45
- package/npm-shrinkwrap.json +2 -2
- package/package.json +2 -2
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
|
-
|
|
33
|
+
Three steps.
|
|
31
34
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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
|
-
|
|
39
|
-
|
|
40
|
-
|
|
39
|
+
```bash
|
|
40
|
+
chattrs setup
|
|
41
|
+
```
|
|
41
42
|
|
|
42
|
-
|
|
43
|
-
|
|
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.
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
`
|
|
76
|
-
|
|
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`.
|
|
223
|
-
|
|
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
|
|
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
|
-
|
|
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: `
|
|
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.
|
package/npm-shrinkwrap.json
CHANGED
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"hasInstallScript": true,
|
|
20
20
|
"license": "MIT",
|
|
21
21
|
"name": "chattrs",
|
|
22
|
-
"version": "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.
|
|
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.
|
|
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.
|
|
82
|
+
"version": "0.6.0",
|
|
83
83
|
"volta": {
|
|
84
84
|
"node": "18.14.1",
|
|
85
85
|
"npm": "9.5.0"
|