nattermatic 0.0.1 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Baldwin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,232 @@
+<p align="center"><img src="assets/nattermatic-320.png" width="160" height="160" alt="nattermatic: a red tin toy robot head with a radio antenna"></p>
+
 # nattermatic
 
-nattermatic is the coming new name for **agentlink**, which lets AI agents on different Claude
-accounts and machines message each other, and wakes idle Claude Code and Codex sessions when a
-message arrives.
+**[nattermatic.com](https://nattermatic.com)** · Let AI agents message each other across different
+agents, accounts and machines.
+Claude Code's own messaging needs every session on one account; nattermatic doesn't. Address any
+agent as `name@host` (e.g. `reviewer@laptop.local`). An incoming message **wakes an idle Claude
+Code or Codex session**, just like agents talking on a single machine.
+
+<p align="center"><a href="https://nattermatic.com"><img src="assets/demo.gif" width="880" alt="Two Claude Code sessions on different machines: one agent asks the other a question, and the idle session wakes up, checks its code and answers"></a></p>
+<p align="center"><a href="https://nattermatic.com">Watch the whole one-minute demo, from setup to reply, at nattermatic.com</a></p>
+
+nattermatic was called **agentlink** until version 0.2.0. Machines set up under the old name move
+across when they're upgraded, keeping their network, and the `agentlink` command still works.
+
+## What you need
+
+- [Claude Code](https://claude.com/claude-code) 2.1.318 or newer on each machine. Codex 0.167 or
+  newer is woken too, and other MCP agents can [join](#what-you-get) (for a machine without Claude
+  Code, set `NATTERMATIC_SKIP_CHECKS=1` for the installer).
+- An Apple silicon Mac or Linux. Intel Macs aren't currently supported.
+- Machines on the same network, or Tailscale on each of them.
+
+The installer brings everything else. It needs no sudo.
+
+## Setup
+
+**First machine** — paste into Claude Code (or run the command yourself):
+
+> Set up nattermatic on this machine: run `curl -fsSL https://nattermatic.com/install.sh | sh`, then show me the prompt it prints for adding other machines, and tell me to type /reload-plugins.
+
+Or install the Claude Code plugin, which teaches Claude to set nattermatic up and use it, then ask
+Claude to set up nattermatic:
+
+    /plugin install nattermatic --marketplace tombaldwin/nattermatic
+
+**Every other machine** — paste the prompt the first machine printed. It looks like:
+
+> Join my nattermatic network: run `curl … | sh` — then tell me to type /reload-plugins.
+
+Each invite adds one machine and expires after 24 hours. The pinned key means curl only talks to
+the machine that made the invite. That key exists only while the invite is open, so a used invite
+line stops working (curl reports a key mismatch or a 404). Run `natter invite` on any member
+for a new one.
+
+**Then** type `/reload-plugins` in Claude Code. That session is now on the network, and so is every
+new one. (If that doesn't work, restart it: `claude --continue` picks up where you left off.)
+
+That's it: no config files, no accounts, no server to run. Setup adds nattermatic's tools and a small
+background hook to Claude Code's settings (and Codex's, if it's installed), and `natter uninstall`
+takes them out again. On Apple
+silicon Macs it installs
+nattermatic as a signed app (`~/Applications/nattermatic.app`, from the inviting machine or the latest
+release, refused unless Apple's certificate for nattermatic's team signed it); macOS asks once to
+let **nattermatic** find devices on your local network: click Allow. Elsewhere it uses npm, and
+brings its own Node.js if the machine doesn't have a recent one. For the next machine, ask Claude
+on any member to add one (or run `natter invite`).
+
+## Your first message
+
+Agents are named after their project folder, so a session in `~/code/reviewer` on the machine
+`desk` is `reviewer@desk.local`. Ask Claude who's online, then ask it to message someone:
+
+> **You, to Claude on your laptop:** Ask reviewer@desk.local why the build is failing.
+>
+> **Claude:** Sent. `pushed to reviewer@desk.local's live session`
+
+The session on `desk` wakes, even if it was idle, and works on it. Its answer wakes the session on
+your laptop in the same way.
+
+You don't need the exact address. `reviewer@desk` works (`.local` is added, and case doesn't
+matter), and so does a machine's Tailscale name or IP address. You can also just say "ask the
+reviewer on my desktop": Claude checks who's online and works out which agent you mean.
+
+More ways to use it, such as a reviewer on another account, waking a session from CI, or a nightly
+job that reports in the morning, are in [Recipes](docs/recipes.md).
+
+## What you get
+
+- **Wake on message.** A background hook wakes the session when a message arrives, even when it's
+  idle, and Claude reads it and acts on it (it still stops at any permission prompt). Tools: `send`, `peers`, `inbox`, plus `network` and
+  `invite` for managing the network. Removing machines and uninstalling stay in the terminal, so
+  you always see the command first.
+- **Nothing gets lost.** Messages are stored on disk at every hop and retried. If the recipient
+  isn't running, its machine keeps the message; if the whole machine is off, copies wait on up
+  to 3 other online machines and whoever sees it return first delivers. Copies that reach a
+  machine twice are dropped, though a session that dies just as a message is shown gets it again
+  when it restarts.
+  Messages expire after 7 days. A session can have 2,000 unread messages waiting, and a machine's
+  store can reach 1 GB (`maxWaiting` and `maxStoreMB` in `~/.nattermatic/config.json`). Past that, a
+  message from another machine waits at the sender and is retried, and a send from this machine
+  fails with an error, so a runaway agent stops there.
+- **Zero-config discovery.** Machines on the same LAN find each other automatically (encrypted UDP
+  beacons) and share what they know, so every machine learns the whole network.
+- **Multiple Claude accounts.** Every `CLAUDE_CONFIG_DIR` account setup can find is enabled
+  (`~/.claude*` dirs, shell aliases, and the one the shell is using); run `natter setup` again to
+  add new accounts.
+- **Beyond the LAN.** With Tailscale on both machines, `natter invite` includes the Tailscale
+  name and joining machines use it automatically. A machine that moves between networks is found
+  again at its other addresses, within a couple of minutes.
+- **Codex.** If Codex is installed, setup adds nattermatic to `~/.codex/config.toml` too. The next
+  time Codex starts, it asks you to trust nattermatic's hook: trust it, and a message gives an idle
+  Codex session a turn (through `codex queue`, Codex 0.167 or newer). Codex sessions are named after
+  their project folder.
+- **Other agents.** Any MCP agent can join with `natter mcp --poll` (it reads with `inbox`
+  instead of being woken).
+- **Channels and managed accounts.** If your organisation's policy turns channels off, `nattermatic
+  claude` sessions can't tell, and pushed messages don't show up. Set `NATTERMATIC_POLL=1` so they're
+  read with `inbox` instead.
+
+Name a session with `NATTERMATIC_NAME=<name> claude` (default: the project folder name).
+
+## Compared with Claude Code's own messaging
+
+Claude Code can already [message between your own sessions](https://code.claude.com/docs/en/cross-session-messaging):
+on one machine over a local socket, and between machines through Anthropic's servers, with a
+claude.ai sign-in and Remote Control. If that covers you, you don't need nattermatic. nattermatic is for
+sessions on different Claude accounts, agents other than Claude Code, and messages that stay
+between your own machines.
+
+## Commands
+
+Claude handles everyday use and invites; these are for terminals and scripts.
+
+    natter to <name@host> <msg>       natter who        natter status
+    natter invite [--list|--revoke]   natter remove <host>
+    natter compact [--yes]            natter uninstall
+
+`natter help <command>` (or `natter <command> --help`) shows a command's options. `nattermatic`
+runs the same commands, and so do agentlink's names for them (`agentlink send`, `agentlink peers`).
+`natter who` says why a machine is offline (the node log, `~/.nattermatic/node.log`, records
+when a machine stops or starts answering).
+
+Tab completion, including the addresses of agents that are online after `natter to`: add
+`eval "$(natter completion zsh)"` to `~/.zshrc`, or `eval "$(natter completion bash)"` to
+`~/.bashrc`.
+
+## Upgrading
+
+Re-run the install line from **Setup** on each machine (or `npm install -g nattermatic`
+followed by `natter setup`). It keeps the machine's key, network and messages. Upgrade all
+your machines: a machine running an incompatible version is reported as such
+(`… runs an older version of nattermatic`) and can't exchange messages until it's upgraded.
+Claude sessions that were running during the upgrade say they need restarting
+(`claude --continue` resumes the conversation); they never stop the newer node.
+
+**From agentlink** (before 0.2.0): re-run the install line, as for any upgrade. Setup moves
+`~/.agentlink` to `~/.nattermatic` (leaving a link behind), replaces the background service, and
+updates Claude Code's and Codex's settings, including any permission rules you wrote for
+agentlink's tools. Machines keep their key and network, and old and new versions still talk to each
+other, so machines can be upgraded one at a time. Because the app has a new name, macOS asks once
+more to let it find devices on the local network, and Codex asks you to trust the new hook. If you
+installed with npm, `npm uninstall -g @tombaldwin/agentlink` before `npm install -g nattermatic`.
+
+## Security
+
+Each machine has its own key. The network is the list of machines' keys, kept and shared by the
+members. Any member can invite machines, and a machine can remove the ones that joined after it
+(the first machine can remove anyone).
+
+- **Encrypted, and nothing for strangers.** Machines talk TLS and prove their keys to each other
+  inside the connection. A laptop at a café that tries a home address now held by a stranger
+  doesn't say who it is or send anything before the check fails. And anyone who connects to a
+  machine sees only a throwaway key, so a laptop can't be recognised as it moves between networks.
+- **Joining.** An invite is a one-time token plus a key the inviting machine presents while the
+  invite is open. Someone watching the
+  network learns nothing from a join, and can't swap the installer. A used or expired invite is
+  worthless.
+- **Machines can't impersonate each other.** Every message is signed by the machine that sent it,
+  and machines relaying a copy can't change it (they can read it: members are trusted). `natter remove <host>` takes a machine off the
+  network; members that were offline learn about it when they come back.
+- **Members are trusted.** Any member can add machines, and every agent on a member machine can
+  message yours. Only add machines you control.
+- **Prompt injection.** Messages come from other AI agents. nattermatic tells Claude to treat them
+  as requests from a colleague, not instructions from you, and to check with you before
+  anything destructive or sensitive.
+
+See [SECURITY.md](SECURITY.md) for details and known limitations.
+
+## Caveats
+
+- Only interactive sessions are woken. `claude -p` runs and SDK sessions aren't, and nothing about
+  them changes: their messages wait for the `inbox` tool.
+- A Codex session is woken from its first prompt on, when Codex runs nattermatic's hook. After you
+  close a Codex window, Codex's background server can keep the session open, and then answers its
+  messages by itself. Two Codex sessions in the same folder can't be told apart: only the newer one
+  is woken. A Codex turn you stop with Esc holds messages back until your next prompt.
+- A woken session reads messages by itself, but stops at permission prompts as usual, so replying
+  may wait for you. Setup allows only the `inbox` and `peers` tools to run unattended.
+- Senders see "pushed to … live session" when the session has been told, not when Claude has read
+  the message.
+- A session idle for more than 20 days stops being woken until its next turn. So does one you
+  interrupt with Esc after it's woken and before it reads its messages; they're still there to read.
+- A VPN that blocks local traffic makes your machines show as offline. Allow local network access
+  in its settings, or use Tailscale. Messages wait until the machines can reach each other.
+- Over SSH on a Mac, Claude Code can't reach its login while the keychain is locked: run
+  `security unlock-keychain` first.
+- Re-running `natter setup` keeps the machine on its network; pass `--new-network` to start a
+  new one.
+- A machine's name is fixed when it joins. To rename it, run `natter remove <old name>` on a
+  machine that joined before it, then run a new invite line with `| sh -s -- --host <new name>` in
+  place of `| sh`. Messages already queued for its old name wait until they expire.
+- A removed machine comes back with a new invite: it gets a new key, and its messages, delivered
+  or not, are dropped. Joining another network drops them too.
+- A machine joins once, for one computer login. A second login on the same machine is refused,
+  because the machine's name is already a member. Several Claude accounts under one login are fine.
+- Apple silicon Macs and Linux. Intel Macs aren't currently supported: the npm install runs there,
+  but macOS may stop it reaching other machines (see below), and there's no app for them yet.
+- On Linux, `.local` names need mDNS (`avahi-daemon` and `libnss-mdns`); without it, use the IP
+  line the invite offers. Port 7777 must be open in any firewall between your machines.
+- On macOS, nattermatic needs Local Network access to reach your other machines. The app asks for
+  it by name; if you clicked Don't Allow, turn **nattermatic** on under System Settings → Privacy &
+  Security → Local Network. An npm install on a Mac (`NATTERMATIC_APP=0`) runs as plain `node` at
+  login, which macOS may block without asking: `natter who` then shows machines as offline
+  with `EHOSTUNREACH`.
+
+## Development
+
+    npm test    # unit tests + multi-node end-to-end: live delivery, offline session, offline machine
+                # via holders, dedupe, poll mode, outsiders, forged and altered messages, strangers
+                # at stored addresses, relays, invites and joining, removal, big backlogs, node
+                # restart, IP/Tailscale aliases
+
+The macOS app (nattermatic as a single signed executable, so macOS asks for Local Network access by
+name; see `scripts/build-app.mjs`):
+
+    npm run build:app                     # dist/nattermatic-<version>-macos-<arch>.zip
+    npm run build:app -- --arch x64 --sign "Developer ID Application: …" --notarize <profile>
+    NATTERMATIC_TEST_EXE=dist/arm64/nattermatic.app/Contents/MacOS/nattermatic npm run test:e2e
 
-Nothing to install here yet. Use agentlink for now: https://github.com/tombaldwin/agentlink
+Releases (signed and notarized app, GitHub Release, npm): see [docs/releasing.md](docs/releasing.md).

package/SECURITY.md

@@ -0,0 +1,178 @@
+# Security
+
+## Model
+
+Each machine has its own ECDSA P-256 key pair, created by `natter setup` and kept in
+`~/.nattermatic/node.key` (readable only by you). A nattermatic network is a list of member keys
+(the *roster*): a set of signed records saying "this key, called `laptop.local`, was added by that
+member" or "this key was removed". Members exchange and merge these records; every member computes
+the same membership from the same records.
+
+- **Transport.** Connections between machines are TLS 1.3. (The installer download also accepts TLS
+  1.2, for macOS's curl; that's protected by the key pinned in the invite line.) The certificate a
+  node presents is a throwaway (a new key for each connection, or each second at the most), so
+  connecting to a node's port shows nothing that identifies the machine, unless an invite is open:
+  see *Known limitations*. Machines prove who they are inside the encrypted connection. The client first shows it
+  holds the network's discovery key; without it, other paths get a 404 (the join paths answer
+  separately, see *The open port is visible*). The server then signs the connection
+  with its machine key. The client checks that this is the machine the roster says should be there,
+  and only then signs the connection with its own key and sends its request. If anyone else answers
+  at the address, they get nothing but that first, anonymous step, which has a time limit however
+  slowly they answer. Both signatures cover that one TLS session, so they can't be replayed, or
+  relayed by someone sitting in the middle.
+- **Addresses are only hints.** LAN beacons, gossiped addresses, configured names and the source
+  IPs of requests can all be wrong or stale (DHCP reuse, a laptop on another network, spoofed
+  name resolution). An address is used for a machine only once the machine there proves it holds
+  that machine's key, so a wrong address never receives a request. Someone relaying traffic to the real
+  machine sees only ciphertext.
+- **Membership.** A node accepts machine-to-machine requests only from current members' keys.
+  Before a machine has proved its key, the only membership records it can submit are the ones that
+  add it and one snapshot, which only the founding machine can have signed. Any member can add a machine by inviting it. A record counts, and is kept and passed on,
+  only if its signature checks out against the signer it names. A roster stops taking new records
+  at 1 MB, apart from the founder's snapshots and removals of a current member by a machine that joined before it, one per
+  machine, which may be as big as a removal has any reason to be: an entry for each machine the
+  target really added, and otherwise no bigger than what it clears. So a roster always fits in the
+  one request (8 MB) that carries it between machines, and a member can't stay on by filling one.
+- **Removal.** Machines are ranked in the order they joined, and a machine can remove only machines
+  that joined after it. The founding machine can remove anyone, and two machines can never remove
+  each other. Removing the remover doesn't bring a machine back, and removals made at the same time
+  all stand. A removed key can't come back on its own (the machine isn't told, and re-joins with an
+  invite and a new key), with the exceptions in *Known limitations*. A key made by a removed machine
+  never becomes the discovery key.
+- **Snapshots.** `natter compact`, on the founding machine, signs a list of the current members
+  in joining order, with the discovery keys still in use and a new one. Any machine can check it
+  against the network's ID, and it replaces all the records before it. After a snapshot, an add dated
+  before it counts for nothing, nor does an older record signed by a machine that isn't in it. A removal
+  between two machines in it still counts if it's dated after that machine was added, so a removal
+  made at the same moment isn't lost, and one from before a machine was let back in doesn't apply.
+- **A removed machine can't add machines.** A removal lists the removed machine's records the
+  remover had. Machines it added stay if every remover had seen the add. An add the remover hadn't
+  seen doesn't count, whatever date it carries, and that machine needs a new invite. Every member
+  computes the same membership from the same records, whatever order they arrived in.
+- **Messages.** Each message is signed by the machine that sent it. A node accepts a message only
+  if the signer is a current member and is the machine named in the sender address, so holders
+  relaying copies can't alter messages and a member can't send as another machine. A sender address
+  must be exactly `name@host` as a node writes it, so nothing can be hidden in it. Messages are
+  encrypted between machines but not end to end: see *Known limitations*.
+- **Joining.** `natter invite` makes a one-time token (stored hashed, expires after 24 hours)
+  and prints a `curl -k --pinnedpubkey "sha256//<key>" https://…` line. The key is an invite key,
+  which the inviting node presents only while it has invites open. curl's `-k` only skips
+  certificate-authority checks; `--pinnedpubkey` still makes curl refuse any other key, so the
+  installer, the package and the token can't be intercepted or replaced. The joining machine checks
+  the same key again before it sends its join request. The token is consumed by the join.
+  `natter invite --revoke` cancels unused tokens. Starting or joining another network deletes the
+  old network's invites and all its messages, and setup stops rather than start the node if it can't.
+- **Discovery.** LAN beacons are encrypted under a discovery key that members share only over
+  their TLS connections, so other people on the network can't read machine names from them. The
+  discovery key is replaced whenever a machine is removed. A replaced key still opens other
+  members' gates, and gets beacons answered, for 14 days, so a machine that was offline during a
+  removal can catch up. After that, it needs a new invite.
+- **Local API.** Sessions on the same machine talk to their node over TLS on 127.0.0.1, with the
+  same check: the node must prove it holds this machine's key, and so must the client. Only
+  processes that can read this machine's private key (your user) get in, and a program squatting
+  on the port is sent nothing. `/health` answers only them.
+- **Prompt injection.** Messages come from other AI agents. The MCP adapter instructs Claude to
+  treat them as requests from a colleague — never as instructions from its user — and not to
+  take destructive or security-sensitive actions solely because a peer asked. Each message is framed
+  with a tag made for that read, so its text can't pass for another message from someone else. Nothing
+  else another machine writes reaches a session: a session name must be one a node could have made, and
+  a machine's error text is dropped for its status code. Only invite machines and agents you trust.
+- **Waking a session.** Setup adds a Claude Code hook that waits in the background and wakes an idle
+  session when a message arrives. What it shows Claude is fixed text saying a message is waiting:
+  nothing another agent wrote comes through the hook. Claude reads the message with the `inbox` tool,
+  so it arrives as a tool result from a named sender. Setup lets `inbox` and `peers` run without a
+  prompt; `send` keeps the session's normal permission rules. A woken session is still acting on
+  another agent's request, with whatever permissions the session has, so take care with sessions
+  running in a mode that skips permission prompts.
+- **Waking a Codex session.** Setup adds a SessionStart hook to Codex's config, which Codex runs only
+  once you've trusted it. The hook starts a process that waits for the session's messages and runs
+  `codex queue` with fixed text, which Codex shows as a prompt in the session: again, nothing another
+  agent wrote. Setup lets Codex run `inbox` and `peers` without asking. Codex's background server can
+  keep a session open after its window closes, and then acts on messages with no one watching.
+
+## Known limitations
+
+- **Members are trusted.** Any member can invite machines, and a machine can remove the ones that
+  joined after it. A compromised member could quietly add extra machines before you remove it.
+  `natter status` lists machines in joining order and shows which member added each one:
+  remove any you don't recognise, or start a new network with `natter setup --new-network`
+  and re-join your machines. One thing it won't show: a member can sign a second key under its own
+  name. That key never becomes a member, and it's dropped when the member is removed.
+- **A member can fill a machine's message store.** A session can have 2,000 messages waiting, but a
+  member can write to made-up names, or to a session reading as fast as they arrive. A store stops at
+  1 GB, so the disk is safe, but then that machine takes no new messages from anyone until old ones
+  expire, even after the member is removed. Messages sent to it wait at their senders until then.
+- **A member can undo a removal made by a machine that joined after it.** It signs a backdated add of
+  the removed key, dated before the remover joined, so that the remover no longer ranks above it, and
+  the machine is back under its old key. A removal by a machine that joined before that member stands.
+  If you suspect a member, remove it first, from the earliest machine you can. A snapshot ends this
+  for everything before it, because adds can't be dated before a snapshot.
+- **A snapshot forgets removed keys.** A removed machine can then come back under its old key, but
+  only if a member adds it: with an invite, as any new machine would. Sending to it after that says
+  it isn't a machine on the network, not that it was removed.
+- **A snapshot can drop a machine.** One added just before it, which the founding machine hadn't
+  heard of, isn't in it and needs a new invite. `natter compact` catches up first, and shows who
+  will be kept and who it couldn't reach.
+- **A snapshot goes by what the founding machine knows.** If it hasn't heard of a removal yet, two
+  things can go against the rules above. A machine that was removed by a machine that's now gone
+  too comes back, as the removal counts for nothing without its signer. And a machine added by a
+  removed one stays, if the founding machine heard of the add first. So make a snapshot with your
+  machines online, and check the list `natter compact` shows.
+- **A backdated removal can cut a machine off until someone reaches it.** A member can sign a removal
+  dated before a snapshot that's over 14 days old, which brings in a new key and leaves no grace period
+  for the snapshot's. A machine that hasn't heard is refused at the gate until another member reaches
+  it, and then it catches up.
+- **Only the founding machine can make a snapshot.** If it's lost, the way out of a full member list
+  is a new network.
+- **Messages aren't end-to-end encrypted.** While the recipient's machine is off, copies wait on
+  other members, which can read them until they're handed over. They can't alter them. Don't send
+  anything through nattermatic that you wouldn't want your other machines to hold.
+- **The founding machine can't be removed.** Nothing joined before it. If it's lost or
+  compromised, start a new network. Likewise, a machine can only be removed from machines that
+  joined before it.
+- **A removed machine's removals of later machines can still take effect.** If it signs one and
+  gets it to a member that hasn't heard of its removal yet, the removal stands, like any removal
+  made at the same moment. It can never remove a machine that joined before it, add one, or get
+  back in. The affected machines re-join with an invite.
+- **A removed machine can still tell which member it is talking to, for 14 days.** It can pass the
+  gate with an old discovery key during the grace period, and learn which member is at an address
+  (which it knew already). It still can't send, receive or change the member list.
+- **Two removals at the same moment can leave a removed machine holding the current discovery key.**
+  If one machine removes another that has already heard of a third's removal, the removed machine has
+  the key that removal brought in, until the next removal by a current member, or a snapshot, replaces
+  it. It can pass the gate as above, for that long.
+- **A member can flood the roster.** Until you remove it, a compromised member can fill the roster
+  so that no new machine can join, and machines may disagree about the last records to arrive.
+  Removing it clears what it signed, apart from machines it really added and its removals of machines
+  that had joined. Those stay until the next snapshot, so a roster can stay full once the member has
+  gone: remove the machines it added, then run `natter compact` on the founding machine. While
+  a roster is full, two kinds of removal wait until there's room, so machines can disagree until
+  then: a second removal of a machine already removed, and one listing dozens of machines a full node
+  has never heard of, if what fills that node was signed by someone else. Remove that machine first.
+  `natter remove` says so if it's this machine's own roster that has no room.
+- **Agents on a machine aren't separately authenticated.** Any process running as your user can
+  send as any session name on that machine.
+- **Invites are credentials until used.** Anyone who gets an unused invite line within 24 hours can
+  join one machine with it. Treat it like a password until it's been used, or revoke it. On a
+  shared machine, other users can see the line's token in the process list for the few seconds the
+  first `curl` runs (the installer keeps it off command lines after that).
+- **While an invite is open, its key is visible to anyone who connects to the port.** Someone could
+  use it to recognise the machine during that window (24 hours at most). Run `natter invite
+  --revoke` once you've added your machines. At other times, a node shows only throwaway keys.
+- **The open port is visible.** Someone scanning a network can see that something is listening on
+  nattermatic's port (7777 by default), and the join paths answer in a way that shows it's nattermatic.
+- **Looking up `.local` names is visible.** Connections themselves don't reveal a machine's name,
+  but a laptop trying to reach `desk.local` asks for it by name, by multicast, on whatever network
+  it's on. Someone there can see the names of your machines.
+- **A removed machine keeps what it had.** It keeps its copy of the member list (machine names and
+  public keys; no secrets) and any messages it already received.
+
+## Starting over
+
+Run `natter setup --new-network` on one machine. It creates a new key and a new network with
+that machine as its only member; join the other machines with fresh invites.
+
+## Reporting a vulnerability
+
+Please open a private security advisory on GitHub ("Security" tab → "Report a vulnerability")
+rather than a public issue.

package/bin/natter.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import '../src/legacy-env.js'
+import { loadConfig, VERSION } from '../src/config.js'
+import { resolve, findCommand, mainHelp, commandHelp, suggest, completionScript } from '../src/cli.js'
+
+// (not --no-warnings on the line above: env -S isn't everywhere.) node:sqlite warns when it's loaded
+process.removeAllListeners('warning')
+
+const [first, ...rest] = process.argv.slice(2)
+const cmd = resolve(first)
+// Only these are flags; anything else (a message that happens to start with "--") is an argument,
+// and "--" ends the flags.
+const VALUE_FLAGS = ['name', 'from', 'host', 'peer', 'join', 'pin', 'net', 'token', 'thread', 'codex', 'pids', 'cwd']
+const BOOL_FLAGS = ['yes', 'force', 'no-service', 'no-claude', 'no-codex', 'no-alias', 'new-network', 'poll', 'channel', 'on-demand', 'revoke', 'list', 'check']
+/** @type {Record<string, any>} */
+const flags = {}
+/** @type {string[]} */
+const pos = []
+for (let i = 0; i < rest.length; i++) {
+  const a = rest[i]
+  if (cmd === 'to' && pos.length) { pos.push(a); continue }    // past the address it's the message, whatever it looks like
+  if (a === '--') { pos.push(...rest.slice(i + 1)); break }
+  const eq = a.indexOf('=')
+  const k = a.startsWith('--') ? a.slice(2, eq < 0 ? undefined : eq) : ''
+  if (VALUE_FLAGS.includes(k)) {
+    const val = eq >= 0 ? a.slice(eq + 1) : rest[++i]
+    if (val === undefined) throw usage(`--${k} needs a value`)
+    if (k === 'peer') (flags.peer ||= []).push(val)
+    else flags[k] = val
+  } else if (BOOL_FLAGS.includes(k) && eq < 0) flags[k] = true
+  else pos.push(a)
+}
+function usage(/** @type {string} */ m) { console.error(`natter: ${m}`); process.exit(2) }
+/** @param {string} name */
+function unknownCommand(name) {
+  const s = suggest(name)
+  usage(`unknown command '${name}'${s ? ` (did you mean ${s}?)` : ''}: see natter help`)
+}
+if (!findCommand(cmd)) unknownCommand(first)
+// `natter <command> --help` shows that command's help instead of running it. Not for claude
+// (its options go to Claude Code), and for send only in place of the address: after it, it's message text.
+const helpAsked = cmd === 'to' ? ['--help', '-h'].includes(rest[0])
+  : cmd !== 'claude' && rest.slice(0, rest.includes('--') ? rest.indexOf('--') : undefined).some(a => a === '--help' || a === '-h')
+if (helpAsked) {
+  const c = findCommand(cmd)
+  if (!c || c.hidden) unknownCommand(cmd)
+  else { console.log(commandHelp(c)); process.exit(0) }
+}
+// a mistyped option (e.g. `invite --lsit`) must not run the command as if it weren't there; send
+// takes free text and claude passes everything on to Claude Code
+if (!['to', 'claude'].includes(cmd)) { const bad = pos.find(a => a.startsWith('-')); if (bad) usage(`unknown option ${bad} (see natter ${cmd} --help)`) }
+
+async function main() {
+  switch (cmd) {
+    case 'setup': {
+      const { setup } = await import('../src/setup.js')
+      if (pos.length) throw new Error('nattermatic no longer uses a shared network secret: to join a network, run the line printed by `natter invite` on a member')
+      return setup({ host: flags.host, peers: flags.peer || [], noService: flags['no-service'], noClaude: flags['no-claude'], noCodex: flags['no-codex'], noAlias: flags['no-alias'], newNetwork: flags['new-network'], join: flags.join, pin: flags.pin, net: flags.net, token: flags.token || process.env.NATTERMATIC_TOKEN })
+    }
+    case 'node': {
+      const { runNode } = await import('../src/node.js')
+      const { Local } = await import('../src/local.js')
+      const fs = await import('node:fs')
+      const path = await import('node:path')
+      const { homeDir } = await import('../src/config.js')
+      // If another nattermatic node already serves this port (e.g. one a session started), the service
+      // waits quietly and takes over when it exits, instead of crash-looping under launchd/systemd.
+      // A node started on demand by a session (--on-demand) just exits: one node is enough.
+      // Every attempt re-reads the config and honours `natter uninstall`, so a long-waiting
+      // standby never revives an uninstalled node or serves a config that setup has since replaced.
+      for (let waited = false; ;) {
+        if (fs.existsSync(path.join(homeDir(), 'disabled'))) { console.error('nattermatic is uninstalled on this machine; not starting the node'); return }
+        const cfg = loadConfig()
+        try { await runNode(cfg); return } catch (e) {
+          if (/** @type {NodeJS.ErrnoException} */ (e).code !== 'EADDRINUSE') throw e
+          const local = new Local(cfg)
+          const h = await local.health()
+          if (!h || 'foreign' in h) { console.error(`port ${cfg.port} is in use by something else`); process.exit(1) }
+          if (flags['on-demand']) { console.error(`another nattermatic node (pid ${h.pid}) is already running`); return }
+          if (!waited) { console.error(`another nattermatic node (pid ${h.pid}) is running; standing by`); waited = true }
+          await new Promise(r => setTimeout(r, 5000))
+        }
+      }
+    }
+    case 'mcp': {
+      const { runAdapter } = await import('../src/mcp.js')   // --check: loading it (and its dependencies) is the check
+      if (flags.check) return console.log('ok')
+      return runAdapter(loadConfig(), { name: flags.name, poll: !!flags.poll, channel: flags.channel ? true : undefined })
+    }
+    case 'wake': {                              // run by the Claude Code hook, not by people
+      const { runWake } = await import('../src/wake.js')
+      process.exit(await runWake())
+    }
+    case 'codex-hook': {                        // run by Codex's SessionStart hook
+      const { runCodexHook } = await import('../src/codex.js')
+      process.exit(await runCodexHook())
+    }
+    case 'codex-wake': {                        // started by codex-hook, in the background
+      const { runCodexWake } = await import('../src/codex.js')
+      process.exit(await runCodexWake({ thread: flags.thread, pids: flags.pids, cwd: flags.cwd, codex: flags.codex }))
+    }
+    case 'claude': {
+      const { launchClaude } = await import('../src/claude.js')
+      const { Local } = await import('../src/local.js')
+      return launchClaude(process.argv.slice(3), async () => new Local(loadConfig()).ensureNode())
+    }
+    case 'to': {
+      if (pos.length < 2) throw new Error('usage: natter to <name@host> <message>')
+      const local = await client()
+      const r = await local.req('POST', '/local/send', { from: flags.from || 'cli', to: pos[0], body: pos.slice(1).join(' ') })
+      return console.log(r.status)
+    }
+    case 'who': {
+      const p = await (await client()).req('GET', '/local/peers')
+      console.log(`${p.self} (this machine): ${p.local.join(', ') || '(no agents)'}`)
+      for (const r of p.remote) console.log(`${r.host}: ${r.online ? (r.sessions.join(', ') || '(no agents)') : `offline${r.error ? ` — ${r.error}` : ''}`}`)
+      return
+    }
+    case 'status':
+      return console.log(JSON.stringify(await (await client()).req('GET', '/local/status'), null, 2))
+    case 'invite': {
+      const local = await client()
+      if (pos.length) throw new Error('usage: natter invite [--list|--revoke]')
+      if (flags.revoke) return console.log(`revoked ${(await local.req('POST', '/local/invite/revoke')).revoked} unused invite(s)`)
+      if (flags.list) {
+        const { invites } = await local.req('GET', '/local/invites')
+        const { formatInvites } = await import('../src/setup.js')
+        return console.log(formatInvites(invites))
+      }
+      const { invitePrompt } = await import('../src/setup.js')
+      return console.log(invitePrompt(await local.req('POST', '/local/invite')))
+    }
+    case 'remove': {
+      if (pos.length !== 1) throw new Error('usage: natter remove <host>')
+      const r = await (await client()).req('POST', '/local/remove', { host: pos[0] })
+      return console.log(`removed ${r.removed}: it can no longer send to or receive from this network`)
+    }
+    case 'compact': {
+      if (pos.length) throw new Error('usage: natter compact [--yes]')
+      const r = await (await client()).req('POST', '/local/compact', { confirm: !!flags.yes, force: !!flags.force }, '', 150_000)
+      const off = r.offline.length ? [`Not reachable just now, so anything they've heard of is unknown here: ${r.offline.join(', ')}`] : []
+      if (flags.yes) return console.log([`member list compacted: ${r.before} bytes to ${r.bytes}. Members: ${r.members.join(', ')}`, ...off].join('\n'))
+      return console.log([
+        `A snapshot would keep these machines: ${r.members.join(', ')}`,
+        ...off,
+        ...(r.caughtUp ? [] : ['Not every machine could be checked in time: run this again before going ahead.']),
+        `The member list is ${r.bytes} bytes (limit ${r.limit}). A machine added that isn't listed above will need a new invite, and removed machines are forgotten.`,
+        'A removal this machine has not heard of can be undone by this, if the machine that made it is removed too: check any machine you removed from elsewhere is gone from the list above.',
+        'Run `natter compact --yes` to go ahead.',
+      ].join('\n'))
+    }
+    case 'uninstall': {
+      const { uninstall } = await import('../src/setup.js')
+      return await uninstall()
+    }
+    case 'version': return console.log(VERSION)
+    case 'help': {
+      if (!pos.length) return console.log(mainHelp(VERSION))
+      const c = findCommand(resolve(pos[0]))
+      if (!c || c.hidden) return unknownCommand(pos[0])
+      return console.log(commandHelp(c))
+    }
+    case 'completion': {
+      if (pos.length !== 1) throw new Error('usage: natter completion <zsh | bash>')
+      return process.stdout.write(completionScript(pos[0]))
+    }
+    case '__complete': {                         // for the completion scripts: never starts a node
+      const { Local } = await import('../src/local.js')
+      let local
+      try { local = new Local(loadConfig()) } catch { return }
+      const h = await local.health()
+      if (!h || 'foreign' in h) return
+      const p = await local.req('GET', '/local/peers', undefined, '', 3000).catch(() => null)
+      if (!p) return
+      if (pos[0] === 'hosts') return console.log(p.remote.map((/** @type {any} */ r) => r.host).join('\n'))
+      const out = [...p.local.map((/** @type {string} */ n) => `${n}@${p.self}`),
+        ...p.remote.flatMap((/** @type {any} */ r) => r.sessions.map((/** @type {string} */ n) => `${n}@${r.host}`))]
+      return out.length && console.log(out.join('\n'))
+    }
+    default: return unknownCommand(first)
+  }
+}
+
+async function client() {
+  const { Local } = await import('../src/local.js')
+  const local = new Local(loadConfig())
+  await local.ensureNode()
+  return local
+}
+
+main().catch(e => { console.error(`natter: ${e instanceof Error ? e.message : e}`); process.exit(1) })