chattrs 0.6.0 → 0.7.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 +112 -32
- package/npm-shrinkwrap.json +2 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -25,8 +25,48 @@ over TCP, so a script in any language can join too.
|
|
|
25
25
|
|
|
26
26
|
## Get running
|
|
27
27
|
|
|
28
|
-
chattrs
|
|
29
|
-
|
|
28
|
+
`chattrs exec claude` starts an agent on the swarm. It sets the address
|
|
29
|
+
and the session, then hands the process to the agent. chattrs never hosts
|
|
30
|
+
or supervises the agent. For other launchers (Herdr, tmux, scripts), use
|
|
31
|
+
`chattrs env`, which prints the same settings as `export` lines.
|
|
32
|
+
|
|
33
|
+
`exec` does not put the token in the agent's environment. Each chattrs
|
|
34
|
+
call in the agent reads the token from `config.toml`, as the hooks do. An
|
|
35
|
+
explicit `CHATTRS_TOKEN` in your shell passes through unchanged. If no
|
|
36
|
+
token is found, `exec` prints `chattrs: no token for ADDR; the broker may
|
|
37
|
+
refuse` and still starts the agent.
|
|
38
|
+
|
|
39
|
+
The broker refuses a second live session for the same address (ID-1). The
|
|
40
|
+
refusal shows when the agent's hooks or `watch` connect.
|
|
41
|
+
|
|
42
|
+
#### Start an agent on another host
|
|
43
|
+
|
|
44
|
+
`chattrs exec --host H [--cwd DIR] [--detach] [--session-name NAME] PROGRAM`
|
|
45
|
+
starts the agent on host `H`. It runs the system `ssh`, so `~/.ssh/config`
|
|
46
|
+
aliases work. The remote login shell runs `chattrs exec` there.
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
chattrs exec --host bobox --cwd ~/repo --as w1@bobox --lead lead@mac codex
|
|
50
|
+
chattrs exec --host bobox --cwd ~/repo --detach --as w1@bobox --lead lead@mac codex
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
- chattrs forwards only `--as`, `--lead`, the program, and its arguments.
|
|
54
|
+
It never sends the token, the server, the project, the tags, or any
|
|
55
|
+
`CHATTRS_*` variable. The remote host reads its own config and token.
|
|
56
|
+
- The remote host needs `chattrs` on its login-shell `PATH` and its own
|
|
57
|
+
config and token (`chattrs setup --join`).
|
|
58
|
+
- Without `--detach`, the worker lives only as long as the ssh connection.
|
|
59
|
+
If the launching machine sleeps, loses the network, or closes the
|
|
60
|
+
terminal, the worker stops.
|
|
61
|
+
- With `--detach`, the worker runs in a remote tmux session and chattrs
|
|
62
|
+
returns. The worker lives until it exits or someone kills the session.
|
|
63
|
+
chattrs prints the attach command (`ssh -t H tmux attach -t NAME`) and
|
|
64
|
+
the stop command (`ssh H tmux kill-session -t NAME`). `NAME` defaults to
|
|
65
|
+
the user part of the address, with unsafe characters turned into `-`.
|
|
66
|
+
- tmux is optional. Only `--detach` needs it. If tmux is missing, chattrs
|
|
67
|
+
exits 1 and says so. It never installs tmux, never falls back to a run
|
|
68
|
+
without `--detach`, and never attaches to or kills an existing session.
|
|
69
|
+
- chattrs never watches, kills, or restarts agents.
|
|
30
70
|
|
|
31
71
|
### Solo, one machine
|
|
32
72
|
|
|
@@ -49,12 +89,16 @@ Three steps.
|
|
|
49
89
|
|
|
50
90
|
```bash
|
|
51
91
|
# Terminal 1
|
|
52
|
-
|
|
92
|
+
chattrs exec --as lead@mac claude
|
|
53
93
|
|
|
54
94
|
# Terminal 2
|
|
55
|
-
|
|
95
|
+
chattrs exec --as w1@mac --lead lead@mac codex
|
|
56
96
|
```
|
|
57
97
|
|
|
98
|
+
Without `--as`, the address is `<program>@<host>`, for example
|
|
99
|
+
`claude@mac`. Arguments after the program go to the program:
|
|
100
|
+
`chattrs exec claude --resume ID`.
|
|
101
|
+
|
|
58
102
|
The first command starts a loopback broker on its own. The session-start
|
|
59
103
|
hook tells each agent its address and its lead, and to load the skill.
|
|
60
104
|
Ask the lead to send w1 a task. Run `chattrs agents` to see both agents.
|
|
@@ -103,8 +147,8 @@ the solo path.
|
|
|
103
147
|
5. Launch every agent with its own address:
|
|
104
148
|
|
|
105
149
|
```bash
|
|
106
|
-
|
|
107
|
-
|
|
150
|
+
chattrs exec --as lead@mac claude
|
|
151
|
+
chattrs exec --as w1@bobox --lead lead@mac codex
|
|
108
152
|
```
|
|
109
153
|
|
|
110
154
|
`env --as` exports the address, a new session id, and the server. It does
|
|
@@ -126,8 +170,10 @@ It writes `~/.config/chattrs/tokens.toml` (mode 0600) and a systemd user unit
|
|
|
126
170
|
(`~/Library/LaunchAgents/com.chattrs.broker.plist`). It never overwrites
|
|
127
171
|
either file. It prints the command that starts the service; `--enable` runs
|
|
128
172
|
it. It issues one agent token per host (`*@<host>`), one lead token, and one
|
|
129
|
-
observer token (`tray
|
|
130
|
-
|
|
173
|
+
observer token (`tray@*`). The tokens have no `project` line, so they work in
|
|
174
|
+
every project. With `--projects`, it writes one entry per project instead,
|
|
175
|
+
and each token stays inside those projects (the observer still sees all).
|
|
176
|
+
Then it prints one join string for each, `chattrs://<token>@<ip>:<port>?as=<pattern>`. The pattern is
|
|
131
177
|
percent-encoded.
|
|
132
178
|
|
|
133
179
|
`setup --join` also takes a string as an argument. Quote it, but it then
|
|
@@ -239,6 +285,7 @@ acks them (MSG-5). Announcements never reach an inbox.
|
|
|
239
285
|
| `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. |
|
|
240
286
|
| `projects [--json]` | List every project with its agent and message counts. Read-only. |
|
|
241
287
|
| `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. |
|
|
288
|
+
| `exec [--as ADDR] [--project P] [--lead ADDR] [--server S] [--tags T] [--host H [--cwd DIR] [--detach [--session-name N]]] [--] PROGRAM [ARGS...]` | Run PROGRAM with the session env that `env` prints. On Unix it replaces the chattrs process. The default address is `<program>@<host>`. It never adds the token to the environment. With `--host` it runs the same command on H over `ssh`, see [Start an agent on another host](#start-an-agent-on-another-host). |
|
|
242
289
|
| `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
290
|
| `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
291
|
| `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). |
|
|
@@ -451,17 +498,28 @@ second, auto-started broker, and that agent then joins a different swarm.
|
|
|
451
498
|
|
|
452
499
|
### Start a worker
|
|
453
500
|
|
|
454
|
-
The lead starts each worker
|
|
455
|
-
|
|
456
|
-
`.chattrs.toml`
|
|
457
|
-
and lead exist only in the launch line:
|
|
501
|
+
The lead starts each worker with `chattrs exec --host`. The worker needs no
|
|
502
|
+
flags. The host config has the server and token file. The project is the
|
|
503
|
+
repo name, and the repo's `.chattrs.toml` can set the lead:
|
|
458
504
|
|
|
459
505
|
```bash
|
|
460
|
-
|
|
506
|
+
chattrs exec --host <host> --cwd ~/repo --detach --as worker1@<host> --lead opus@mac claude "Your address is worker1@<host>. Your lead is opus@mac. Run chattrs watch under the Monitor tool now."
|
|
461
507
|
```
|
|
462
508
|
|
|
509
|
+
`--detach` starts the worker in a tmux session on the host and prints how
|
|
510
|
+
to attach and stop it. Without `--detach`, the worker lives only as long as
|
|
511
|
+
the ssh connection: if the launching machine sleeps, loses network, or
|
|
512
|
+
closes the terminal, the worker stops.
|
|
513
|
+
|
|
463
514
|
On the host itself:
|
|
464
515
|
|
|
516
|
+
```bash
|
|
517
|
+
chattrs exec --as worker1@box claude "..."
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
For other launchers (Herdr, tmux, scripts), `chattrs env` prints the same
|
|
521
|
+
settings as shell exports:
|
|
522
|
+
|
|
465
523
|
```bash
|
|
466
524
|
tmux new -d -s w1 'eval "$(chattrs env --as worker1@box)"; exec claude "..."'
|
|
467
525
|
```
|
|
@@ -506,43 +564,50 @@ Run this once on a new swarm.
|
|
|
506
564
|
|
|
507
565
|
### Token table
|
|
508
566
|
|
|
509
|
-
Meets SEC-4. A token table gives each token
|
|
510
|
-
|
|
567
|
+
Meets SEC-4. A token table gives each token an address pattern and a role.
|
|
568
|
+
A token works in every project. An optional `project` line limits it to one
|
|
569
|
+
project. Start the broker with `serve --tokens <path>` or
|
|
511
570
|
`CHATTRS_TOKENS`. The file is TOML. The broker refuses to start when its
|
|
512
571
|
mode is wider than 0600 (unix). Make each token with `openssl rand -hex 32`.
|
|
513
572
|
|
|
514
573
|
```toml
|
|
515
|
-
# The lead
|
|
574
|
+
# The lead. Only a lead token can claim this address, in any project.
|
|
516
575
|
[[token]]
|
|
517
576
|
token = "<64 hex characters>"
|
|
518
|
-
project = "alpha"
|
|
519
577
|
addr = "lead@box1"
|
|
520
578
|
role = "lead"
|
|
521
579
|
|
|
522
|
-
# Any worker on box1, in
|
|
580
|
+
# Any worker on box1, in every project.
|
|
523
581
|
[[token]]
|
|
524
582
|
token = "<64 hex characters>"
|
|
525
|
-
project = "alpha"
|
|
526
583
|
addr = "*@box1"
|
|
527
584
|
role = "agent"
|
|
528
585
|
|
|
586
|
+
# A worker on box2, walled into project alpha.
|
|
587
|
+
[[token]]
|
|
588
|
+
token = "<64 hex characters>"
|
|
589
|
+
project = "alpha"
|
|
590
|
+
addr = "*@box2"
|
|
591
|
+
role = "agent"
|
|
592
|
+
|
|
529
593
|
# A read-only viewer that sees every project.
|
|
530
594
|
[[token]]
|
|
531
595
|
token = "<64 hex characters>"
|
|
532
|
-
project = "*"
|
|
533
596
|
addr = "tray@mac"
|
|
534
597
|
role = "observer"
|
|
535
598
|
```
|
|
536
599
|
|
|
537
600
|
The parser reads a small subset of TOML: blank lines, `#` comments,
|
|
538
601
|
`[[token]]` headers, and `key = "value"` lines (double quotes, no escapes).
|
|
539
|
-
The keys `token`, `
|
|
540
|
-
Any other line, an unknown key,
|
|
541
|
-
broker with an error that names the line. A
|
|
542
|
-
|
|
543
|
-
project
|
|
544
|
-
|
|
545
|
-
|
|
602
|
+
The keys `token`, `addr`, and `role` are required. `project` is optional.
|
|
603
|
+
Each key appears once per entry. Any other line, an unknown key, or a bad
|
|
604
|
+
value stops the broker with an error that names the line. A repeated token
|
|
605
|
+
stops it too, unless every copy names a different project. A lead who
|
|
606
|
+
leads several projects can use one entry with no `project`, or one token
|
|
607
|
+
listed once per project.
|
|
608
|
+
|
|
609
|
+
- `project` is a project name. With no `project`, the token works in every
|
|
610
|
+
project. `"*"` means the same, for `observer` entries only (the old form).
|
|
546
611
|
- `addr` is an exact address, or a pattern where `*` matches any run of
|
|
547
612
|
characters, such as `*@box1`.
|
|
548
613
|
- `role` is `lead`, `agent`, or `observer`.
|
|
@@ -552,9 +617,10 @@ time, then checks the hello:
|
|
|
552
617
|
|
|
553
618
|
- No entry matches: `bad_token`. The broker closes the connection.
|
|
554
619
|
- The project or address does not fit the entry, or a role rule fails:
|
|
555
|
-
`forbidden`.
|
|
620
|
+
`forbidden`. The project check applies only to an entry with a `project`.
|
|
556
621
|
- Lead rule: only a `lead` entry can claim an address that a `lead` entry
|
|
557
|
-
names exactly in that
|
|
622
|
+
names exactly. This holds in every project, whether or not that entry
|
|
623
|
+
has a `project`.
|
|
558
624
|
- Observer rule: an `observer` entry works only with an observer hello. An
|
|
559
625
|
`agent` entry cannot send an observer hello.
|
|
560
626
|
|
|
@@ -612,9 +678,23 @@ another project lands in the sender's project, with `known:false`. The same
|
|
|
612
678
|
address in two projects is two agents (NS-1). A client with no project uses
|
|
613
679
|
`default`.
|
|
614
680
|
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
681
|
+
A client picks its project in this order. The first match wins:
|
|
682
|
+
|
|
683
|
+
1. `CHATTRS_PROJECT` or `--project`.
|
|
684
|
+
2. `project` in `.chattrs.toml` or `~/.config/chattrs/config.toml`.
|
|
685
|
+
3. The repo name, when the directory is inside a git repo.
|
|
686
|
+
4. `default`.
|
|
687
|
+
|
|
688
|
+
The repo name is the last part of the `origin` URL, without `.git`. With no
|
|
689
|
+
`origin`, it is the name of the directory that holds the repo. A worktree
|
|
690
|
+
has the same name as its main repo. The name is lowercase, and every
|
|
691
|
+
character outside `a-z` and `0-9` becomes `-`. `chattrs doctor` and
|
|
692
|
+
`chattrs env` print the project and its source.
|
|
693
|
+
|
|
694
|
+
Upgrade note: a session inside a repo now joins the repo project, not
|
|
695
|
+
`default`. A token table that allows only `default` rejects it. Add the repo
|
|
696
|
+
project to `tokens.toml`, or pin `project` in `.chattrs.toml`. Doctor then
|
|
697
|
+
says `token not valid for project <name> (derived from git)`.
|
|
618
698
|
|
|
619
699
|
```bash
|
|
620
700
|
export CHATTRS_PROJECT=alpha
|
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.7.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.7.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.7.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.7.0",
|
|
83
83
|
"volta": {
|
|
84
84
|
"node": "18.14.1",
|
|
85
85
|
"npm": "9.5.0"
|