Skip to content
Back to search

worldinmotion

MarketplaceWorks with Claude CodeGitHub

worldinmotion: real-time, end-to-end encrypted messaging between AI agent sessions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/distronode-corporation/worldinmotion with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/distronode-corporation/worldinmotion'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/distronode-corporation--worldinmotion/badge.svg)](/listings/distronode-corporation--worldinmotion)

HTML

<a href="/listings/distronode-corporation--worldinmotion"><img src="/api/listings/distronode-corporation--worldinmotion/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

[Terminal] On the first machine, with Node.js 22.18 or newer, in a terminal you opened yourself:

npx worldinmotion setup

Or install `wim` first (step 1 below) and run `wim setup`, which is the same. It creates the mesh, shows its recovery code once, offers the Claude Code plugin and the VS Code extension, configures the other agents it finds, and ends with `wim status`. To add another machine, run `wim invite` on one already in the mesh, then `npx worldinmotion setup <code>` on the new one. [First run](#first-run-three-machines-one-person) says what each step does.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "name": "worldinmotion",
  3. "owner": {
  4. "name": "Distronode Corporation"
  5. },
  6. "description": "worldinmotion: real-time, end-to-end encrypted messaging between AI agent sessions.",
  7. "plugins": [
  8. {
  9. "name": "worldinmotion",
  10. "source": {
  11. "source": "git-subdir",
  12. "url": "https://github.com/distronode-corporation/worldinmotion.git",
  13. "path": "plugins/claude-code",
  14. "ref": "v1.0.3",
  15. "sha": "a9dcee6e93c83297d82981e2b1dbb391040726db"
  16. },
  17. "description": "End-to-end encrypted messages between AI agent sessions across machines and accounts."
  18. }
  19. ]
  20. }
README.md · README · 923 lines
  1. <picture>
  2. <source media="(prefers-color-scheme: dark)" srcset=".github/assets/distronode-logo-dark.png">
  3. <source media="(prefers-color-scheme: light)" srcset=".github/assets/distronode-logo-light.png">
  4. <img alt="Distronode" src=".github/assets/distronode-logo-light.png" width="220">
  5. </picture>
  6. # worldinmotion
  7. [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15869/badge)](https://www.bestpractices.dev/projects/15869)
  8. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/distronode-corporation/worldinmotion/badge)](https://scorecard.dev/viewer/?uri=github.com/distronode-corporation/worldinmotion)
  9. [![Latest release](https://img.shields.io/github/v/release/distronode-corporation/worldinmotion?label=release)](https://github.com/distronode-corporation/worldinmotion/releases)
  10. [Listed on mcpservers.org](https://mcpservers.org/servers/distronode-corporation/worldinmotion)
  11. worldinmotion lets AI agent sessions (Claude Code, Codex CLI, Gemini CLI, Antigravity, Cursor,
  12. Copilot CLI, Claude Desktop, bots) send each other messages in real time, across machines and
  13. across accounts. Messages are end-to-end
  14. encrypted between devices and pass through a relay that cannot read them. Each session gets an
  15. address like `reviewer@laptop`, and can see who is online, send, wait for a reply, and join rooms.
  16. ![Two sessions on one machine: writer sends reviewer a message, reviewer answers, each watching in its own terminal](docs/images/terminal.png)
  17. *Two sessions talking through `wim`, drawn from a transcript recorded with wim 0.1.7.*
  18. No account required, no telemetry, sealed offline delivery.
  19. > **Status: 1.0.** The wire format (`wim/1`) and the commands are stable: a change that breaks
  20. > either needs a new major version. Crossing accounts is how it is built (a mesh never uses a
  21. > vendor account), but the formal two-account test has not run yet.
  22. ## Why
  23. **Encrypted messages between AI agents from different vendors and different accounts, with a
  24. trust model a security team can review.**
  25. - **Different vendors.** Claude Code, Codex CLI, Gemini CLI, Antigravity, Cursor, Copilot CLI,
  26. Claude Desktop, any other MCP client and a plain model API (`wim bot`) all reach the same mesh.
  27. `wim setup` configures each one it finds ([Other agents](#other-agents)).
  28. - **Different accounts.** A mesh is a set of device keys you create, not a vendor account, so a
  29. session under your account and one under a client's can talk directly.
  30. - **A trust model you can review.** Your own devices are trusted inside the approvals you already
  31. give, anything else is held for you, and with the signer an agent cannot approve what is held
  32. ([Security, in plain words](#security-in-plain-words)). [SECURITY-MODEL.md](SECURITY-MODEL.md)
  33. is the full threat model, and [docs/security-teams.md](docs/security-teams.md) maps it to the
  34. OWASP agent risks and names the gaps.
  35. Built-in messaging stays inside one vendor and one account, through that vendor's servers. Since
  36. August 2026 (Claude Code v2.1.224), Claude Code sessions on one account can message each other
  37. across machines, through Anthropic's servers. Beyond one machine that needs a claude.ai sign-in,
  38. so it does not work with an API key or on Amazon Bedrock, Google Cloud or Microsoft Foundry.
  39. worldinmotion is for what that does not cover: sessions under different accounts or
  40. organisations, agents from different vendors, and a path in the middle that cannot read the
  41. messages (each agent's own model provider still sees what that agent reads). Without it, when
  42. two such agents work on the same problem (one writing code under your account, one reviewing it
  43. under a client's), a person ends up copying text between them.
  44. What the line at the top means:
  45. - **No account required.** A mesh is a set of device keys that you create. The hosted relay needs
  46. no sign-up, and no vendor account is involved.
  47. - **No telemetry.** The client, the Claude Code plugin and the VS Code extension send no usage
  48. data. The client connects only to the relay you choose (and, for `wim bot` and `wim ci`, to the
  49. provider you configure). Crash reports are off unless you turn them on, see
  50. [Crash reports (opt in)](#crash-reports-opt-in).
  51. - **Sealed offline delivery.** A message to a session that is offline waits on the relay for up to
  52. 24 hours, sealed to the recipient's device, while the sender may go offline too.
  53. ## Quick start: `wim setup`
  54. [Terminal] On the first machine, with Node.js 22.18 or newer, in a terminal you opened yourself:
  55. ```sh
  56. npx worldinmotion setup
  57. ```
  58. Or install `wim` first (step 1 below) and run `wim setup`, which is the same. It creates the mesh,
  59. shows its recovery code once, offers the Claude Code plugin and the VS Code extension, configures
  60. the other agents it finds, and ends with `wim status`. To add another machine, run `wim invite` on
  61. one already in the mesh, then `npx worldinmotion setup <code>` on the new one.
  62. [First run](#first-run-three-machines-one-person) says what each step does.
  63. ## First run: three machines, one person
  64. This guide sets up one person's three machines (here `laptop`, `desk` and `build`) on one mesh,
  65. using the hosted relay at `wss://worldinmotion.distronode.com`, which is free. Read its
  66. [terms](docs/hosted-relay.md) first. To run your own relay instead, see
  67. [Self-hosting a relay](#self-hosting-a-relay).
  68. Every step says where it happens:
  69. - **[Terminal]** a terminal you opened yourself (in VS Code: Terminal > New Terminal). Never the
  70. Claude chat box, and never `!` in Claude Code: both run the command inside Claude's session,
  71. where `wim` refuses the steps that ask for a passphrase, show a secret, decide trust, approve
  72. a held message or delete a mesh (it says so: `CLAUDECODE is set: this shell belongs to Claude
  73. Code`).
  74. - **[Claude chat]** the Claude Code prompt.
  75. - **[VS Code]** the VS Code window itself (Extensions view, command palette).
  76. `wim setup` does steps 1 to 4 for you. [By hand](#by-hand) does the same with `wim init`, `wim
  77. join` and `wim invite`, which stay as they are for scripts and unattended machines. Steps 5 to 12
  78. apply either way.
  79. ### With `wim setup`
  80. #### The first machine
  81. [Terminal on `laptop`]
  82. ```sh
  83. npx worldinmotion setup
  84. ```
  85. Run through `npx`, it first says that it runs from npx's cache, which npm prunes, and offers to
  86. install this same version with `npm install --global worldinmotion@<version>` once you type
  87. `y`. When npm's global prefix is not writable, it offers `~/.npm-global` instead and says how
  88. to put its `bin` on `PATH`; it never uses `sudo`. It then runs `wim setup` again from the
  89. installed copy, so every agent config points at a path that stays. If you answer `n`, it prints
  90. the install command and stops, changing nothing. With `wim` installed already, run `wim setup`.
  91. It asks for what it needs and says what each step does before it takes it:
  92. 1. Choose 1 to create a new mesh here. It offers this machine's host name as the device name and
  93. the hosted relay, `wss://worldinmotion.distronode.com` ([terms](docs/hosted-relay.md)), shows
  94. what the relay says it offers, and creates the mesh only after you type `y`.
  95. 2. It shows the **recovery code** once and waits until you press Enter. Keep it offline (a
  96. password manager, or paper): it is as powerful as an admin device. Never paste it into a
  97. Claude chat or send it over the mesh.
  98. 3. When it finds the `claude` command, it offers the Claude Code plugin and shows the two commands
  99. it runs, `claude plugin marketplace add distronode-corporation/worldinmotion` and
  100. `claude plugin install worldinmotion@worldinmotion`. When it finds `code`, it offers the VS
  101. Code extension, `code --install-extension distronode.worldinmotion`. Each waits
  102. for a `y`. It prints the state directory and why it is that one, and warns when
  103. `CLAUDE_CONFIG_DIR` is set, since a Claude Code tab without it is another device.
  104. 4. For each other agent it finds (Codex CLI, Gemini CLI, Antigravity CLI, Cursor, Copilot CLI,
  105. Claude Desktop), it shows the change to that agent's config as a diff: the worldinmotion MCP
  106. server with the read-only tools, and the `wim hook` entries ([Other agents](#other-agents)).
  107. Each file waits for a `y`, and the original is kept beside it.
  108. 5. It ends with `wim status`, problems first.
  109. Run it again whenever you like: on a machine that is set up, it skips what is done and repeats
  110. its steps 3 to 5. In an agent's shell, or with its input or output piped, it refuses and says why.
  111. It never asks about crash reports, and it does not start the signer
  112. ([step 5](#5-optional-keep-the-keys-out-of-claudes-reach) below).
  113. #### Each other machine: `wim setup <invite code>`
  114. Do this once for `desk` and once for `build`, with a new invite each time.
  115. [Terminal on `laptop`]
  116. ```sh
  117. wim invite
  118. ```
  119. It asks "Is the new device one of yours?": answer `y` for your own, and `laptop` trusts it once it
  120. is admitted. It then prints a single-use invite code, `wim2-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`, and
  121. waits. Move the code to the other machine yourself (a password manager, AirDrop, a USB stick, or
  122. read it out), never through Claude or another agent, and not over the mesh.
  123. [Terminal on `desk`]
  124. ```sh
  125. npx worldinmotion setup <code>
  126. ```
  127. (or `wim setup <code>` with `wim` installed). It joins as `wim join` does, naming the device after
  128. the host name unless you add `--name desk`. `desk` shows a comparison code like `7KQ2M-X4D9P`:
  129. type it on `laptop`, where `wim invite` asks for it. It then asks whether `laptop`, the device
  130. that admitted it, is your own, and then about each other device on its own (step 4 says what that
  131. trust means). After that it offers its steps 3 to 5, as on the first machine.
  132. From here, go on with [step 5](#5-optional-keep-the-keys-out-of-claudes-reach) (optional) and the
  133. checks from step 6.
  134. ### By hand
  135. Steps 1 to 4 do by hand what `wim setup` does.
  136. #### 1. Install, on each machine
  137. You need Node.js 22.18 or newer.
  138. [Terminal] Install the `wim` command:
  139. ```sh
  140. npm install --global worldinmotion
  141. wim --version
  142. ```
  143. Or, with [Homebrew](https://brew.sh) on macOS or Linux, which also installs Homebrew's Node.js:
  144. ```sh
  145. brew install distronode-corporation/tap/worldinmotion
  146. wim --version
  147. ```
  148. After `brew upgrade` (of `worldinmotion` or of `node`), run `wim setup` again: it offers the new
  149. paths as an update.
  150. If the shell then says `wim: command not found` after the npm install, npm's global bin directory
  151. is not on your `PATH`. Fix it for this shell, and add the same line to `~/.bashrc` or `~/.zshrc`:
  152. ```sh
  153. export PATH="$(npm prefix -g)/bin:$PATH"
  154. ```
  155. Without npm: download `wim.mjs` and `SHA256SUMS` from the latest
  156. [GitHub Release](https://github.com/distronode-corporation/worldinmotion/releases), check it with
  157. `sha256sum -c SHA256SUMS` (macOS: `shasum -a 256 -c SHA256SUMS`), and install it with
  158. `install -m 755 wim.mjs ~/.local/bin/wim`, or run `node wim.mjs` wherever this guide says `wim`.
  159. [Claude chat] Install the Claude Code plugin:
  160. ```
  161. /plugin marketplace add distronode-corporation/worldinmotion
  162. /plugin install worldinmotion@worldinmotion
  163. ```
  164. A Claude Code session that was already open does not get the plugin: start new ones.
  165. [VS Code] Optional: install the extension, `distronode.worldinmotion` on the Visual Studio
  166. Marketplace and Open VSX. Search for **worldinmotion** in the Extensions view, or run
  167. `code --install-extension distronode.worldinmotion`. Releases before 1.0 were published as
  168. pre-releases: if you installed one, choose **Switch to Release Version** on the extension's page in
  169. VS Code to follow releases.
  170. [Verify a download](#verify-a-download) checks the npm package, the GitHub Release file and the
  171. relay image against the release workflow that built them, and [Uninstall](#uninstall) removes
  172. everything these steps install.
  173. #### 2. Create the mesh, on the first machine
  174. [Terminal on `laptop`]
  175. ```sh
  176. wim init --name laptop --relay wss://worldinmotion.distronode.com
  177. ```
  178. This makes the device's keys, creates a new mesh on the relay with this device as its admin, and
  179. shows a **recovery code** once. Keep it offline (a password manager, or paper): it is as powerful
  180. as an admin device. Never paste it into a Claude chat or send it over the mesh.
  181. Run anywhere it cannot be shown, such as through an agent or a pipe, `wim init` says why, offers
  182. the code to `wim recovery show` run in your own terminal, and **keeps running until you collect
  183. it, for up to 10 minutes**: only that process holds the code. If it is stopped before then (Ctrl-C,
  184. or an agent giving up on it), it exits 130, the code is gone and the mesh has none; run `wim
  185. recovery rotate` on this machine, in your own terminal, for a new one. `wim recovery show --wait`
  186. keeps the code on screen until you press Enter, for a terminal that closes as soon as its command
  187. ends.
  188. `wim devices` lists that code as a second admin named `recovery`, marked `hold`. It is not a
  189. machine: it is an admin record that never connects, so nothing ever comes from it.
  190. `wim init` ends by pointing to `wim status`, which checks the device, the relay and the mesh in a
  191. few lines (step 6). Right after `init`, `wim peers` says "No other sessions.": that is expected
  192. until another device joins.
  193. #### 3. Add the other two machines
  194. Do this once for `desk` and once for `build`, with a new invite each time.
  195. [Terminal on `laptop`]
  196. ```sh
  197. wim invite
  198. ```
  199. It prints a single-use short invite code, `wim2-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`, and waits. Move
  200. the code to the other machine yourself: a password manager, AirDrop, a file on a USB stick, or
  201. read it out. Never through Claude or another agent, and not over the mesh. (A machine on wim
  202. 0.1.10 or older cannot read it: upgrade it to 0.2.0 before it joins.)
  203. [Terminal on `desk`]
  204. ```sh
  205. wim join <code> --name desk
  206. ```
  207. `desk` shows a comparison code like `7KQ2M-X4D9P`. Type it on `laptop`, where `wim invite` asks
  208. for it: `laptop` never shows its own copy, so typing it is the check that the request came from
  209. `desk` and not from someone else who saw the invite. A code that does not match is refused: make
  210. a new invite. Both commands ask for a person at the terminal, so run them in a terminal you
  211. opened yourself, not through an agent.
  212. `wim join` makes the device's keys too, so a new machine needs no `wim init`. If `wim invite` was
  213. no longer running when `desk` asked to join, `wim devices pending` on `laptop` lists it, and
  214. `wim devices admit desk <comparison code>` admits it.
  215. For an unattended machine you control (a bot or a build box), `wim invite --auto` admits the first
  216. device that uses the code, with no comparison code to type. Because that code alone admits a
  217. device, it is printed only in a terminal you opened yourself. Run through an agent or with its
  218. output piped, `wim invite --auto` keeps the code in memory and asks you to run `wim invite show`
  219. in your own terminal, within 10 minutes and before the invite expires, to see it once.
  220. #### 4. Trust your own devices
  221. Until you trust a device, its messages are held for your approval. Trust is set inside the
  222. approvals you already give, between the two devices of each one, and never passed on:
  223. - `wim invite` asks "Is the new device one of yours?" before it shows the code. Answer `y` for
  224. your own, and `laptop` trusts `desk` when it admits it (`wim invite --auto` never trusts).
  225. - `wim join` (or `wim setup <code>`) on `desk` asks "laptop admitted this device. Is laptop your
  226. own device?", then about each other device on its own.
  227. - A device added later by another device is not trusted because that device is: `wim status`
  228. lists it ("held here, added by laptop: build"), and VS Code asks about it.
  229. Each automatic trust prints its undo, `wim devices untrust <name>`. In a mesh with someone else's
  230. devices, answer no for theirs. Any you skipped, or a mesh made before 0.2.0, on each machine:
  231. [Terminal on `laptop`, `desk` and `build`]
  232. ```sh
  233. wim devices trust --all
  234. ```
  235. `wim devices trust <name>` trusts one device, and `wim devices` lists the devices and what this
  236. one does with each one's messages. Both trust commands list each device with its id and wait for
  237. your `y`; the id should match the line marked `this device` in `wim devices list` on that machine.
  238. ### Either way, on every machine
  239. #### 5. Optional: keep the keys out of Claude's reach
  240. By default the device keys are in a file your OS user can read, and so can any agent with a
  241. shell. The signer keeps them in a separate process instead.
  242. [Terminal] Once per machine:
  243. ```sh
  244. wim signer encrypt # once: encrypts the key file under a passphrase you choose
  245. wim signer start # asks for the passphrase and starts the signer in the background
  246. ```
  247. The signer keeps running after you close the terminal or VS Code, and stops when you log out,
  248. restart or run `wim signer stop`. To have it start at each log in, run
  249. `wim signer autostart enable` once: a login item starts it and asks for the passphrase in a dialog
  250. of its own (`--keyring` keeps the passphrase in the macOS keychain or libsecret instead; read
  251. SECURITY-MODEL.md section 5.8 first). Without autostart, run `wim signer start` again after each
  252. restart.
  253. Start it before you open Claude when you can. A Claude tab opened earlier says on its status line
  254. that no signer is running, and links by itself a few seconds after the signer starts.
  255. `wim signer status` only reads, so Claude may run it for you; `wim signer lock` wipes the keys from
  256. the signer's memory until `wim signer unlock`.
  257. With the keys in the signer, approving or refusing a held message also needs the signer's own
  258. confirmation, so an agent cannot approve one by writing a file (step 10).
  259. The signer used to be `wim agent`. The old `wim agent start`, `stop`, `status`, `lock`, `unlock`,
  260. `encrypt`, `decrypt` and `autostart` still run it, with a note that names the new command, and
  261. `wim signer autostart status` updates a login item written for the old name.
  262. #### 6. Check each machine
  263. [Terminal] `wim status` sums it up: this device, whether it refuses v0.1 boxes (`wim legacy-boxes`),
  264. each mesh with its relay, whether this device is an admin, how many other devices and live
  265. sessions there are, any device another device added that is still held here, how long the relay
  266. keeps a mesh nobody uses, every takeover of a session's address in the last 24 hours, and any
  267. problem in full. `wim doctor` shows every check behind it: the keys, the
  268. state directory (and why it is the one: `WIM_HOME`, `CLAUDE_CONFIG_DIR` or the default), how held
  269. messages are decided here, the relay, the clock and the roster, and any other device directory on
  270. the machine. Both check every
  271. mesh the device is in, and on a machine not set up yet they say so and name `wim init` and `wim
  272. join`. Either exits 1 when it finds a problem.
  273. [Claude chat] In a new Claude Code tab, `/wim status` shows the same for that tab: its address,
  274. the relay connection, the signer and the state directory.
  275. [Terminal] `wim test` checks wim itself on this machine, without touching your device or your
  276. meshes. It starts a relay inside its own process on `127.0.0.1`, makes throwaway devices in a new
  277. temporary directory, and runs the real commands on them: create, invite and join with the
  278. comparison code, trust, ping, send with receipts, the offline queue, held messages approved and
  279. refused, rooms, a file, a lease, ask and reply, rename, the loop breaker, `wim status` and `wim
  280. doctor`, and `wim mesh delete`. It plays the person for the steps that need one, on its own
  281. devices only, and removes everything at the end. It prints one row per step and exits 0 only when
  282. every step passed; `wim test --json` prints the same as JSON. `wim test --full` adds the signer
  283. (encrypt, start, lock, unlock, stop) and a CI notice from a test issuer that exists only inside
  284. the sandbox. `wim test --relay wss://<relay>` runs the same steps on a real relay instead, with a
  285. throwaway mesh it deletes at the end (`--key-env NAME` for a relay that needs an operator key to
  286. create one); a step that relay does not offer is skipped, which does not fail the run.
  287. `--person` has you type the steps that need a person. In VS Code, **worldinmotion: Run
  288. Self-Test** runs the same in the sandbox and shows the rows in an output channel; in Claude Code,
  289. `/wim test` does, taking `--full` and `--relay` only when you type them (a relay that needs an
  290. operator key is tested from a terminal). SECURITY-MODEL section 7.6 says what it
  291. can and cannot touch.
  292. #### 7. Addresses
  293. | address | what it is |
  294. |---|---|
  295. | `cli@<device>` | the device's terminal inbox: `wim inbox` reads it once (`--peek` to look without marking anything read; a pipe or file marks nothing unless `--mark-read`), `wim watch` follows it. Registered when the device creates or joins the mesh; the relay forgets it after 24 hours offline with nothing queued, and the next `wim inbox` or `wim watch` there registers it again |
  296. | `<folder>@<device>` | a Claude Code tab: its working directory's base name, for example `billing@laptop`. The tab's status line shows it; `/wim name <name>` renames it |
  297. | `vscode@<device>` | the VS Code extension |
  298. A name a session holds stays its own while it is offline (24 hours, longer while messages wait),
  299. so a new session that asks for it gets `name-2`. To take a role's address over on the same device,
  300. ask for it: `--take` with `--as <name>`, `WIM_TAKE=1` with `WIM_NAME`, or the `rename` tool with
  301. `take`. The new session then gets that address with its queue, held items and leases, and a notice
  302. that counts them; a name a live session holds is never taken (docs/design.md, "Taking a session
  303. back").
  304. A message to `cli@desk` waits in desk's terminal inbox; it does not reach a Claude tab on `desk`.
  305. When a Claude tab is live there, `wim send` says so: `live on desk now: billing@desk (claude-code)`.
  306. #### 8. Terminal test: all six routes
  307. [Terminal on each machine] Leave `wim watch` running in one terminal, so each machine has a live
  308. session. Then, in another terminal on each machine:
  309. ```sh
  310. wim ping --all
  311. ```
  312. It pings every live session, and each device's client answers with a pong by itself (no agent,
  313. no inbox). A pong proves both directions between the two devices, encryption included, so three
  314. machines that each print `both directions ok` for the other two have tested all six routes.
  315. To test real messages as well, send to the other two from each machine and wait for the
  316. receipts:
  317. ```sh
  318. # on laptop
  319. wim send cli@desk "hello from laptop" --wait 2m
  320. wim send cli@build "hello from laptop" --wait 2m
  321. # on desk, then on build: the same to the other two
  322. ```
  323. Each send answers `routed` (handed to a live session; not yet read) while a `wim watch` reads
  324. there, else `queued`. The `wim watch` on the other machine prints the message, and the waiting
  325. `wim send` prints `delivered` once that session has taken it. Answer each one to test the way
  326. back, for example on `desk`: `wim send cli@laptop "reply from desk" --wait 2m`. Without a
  327. `wim watch`, `wim inbox` reads the terminal inbox once and, at a terminal, marks each item read
  328. once it is printed. When its output is not a terminal (a pipe or a file) it marks nothing, since a
  329. pipe such as `| head` can cut an item off part-way without the writer knowing, and it says so on
  330. stderr; `--mark-read` marks what it printed anyway. `wim inbox --peek` prints it all and marks
  331. nothing. A message from a device you did not trust prints `held` with how to approve
  332. it there (`wim held approve <id>`, in a terminal on that machine: it shows everything held from
  333. that device together, with the count and the time span, and approves exactly those on a typed
  334. `all`, or only that one on `one`). A `wim send --wait` keeps waiting through `held` and prints `delivered`
  335. once the person there approves it, or `refused` if they refuse it. When that device's loop
  336. breaker holds it for a trusted device's cool-down, it says when the cool-down ends, and prints
  337. `delivered` when that device's client delivers it then.
  338. #### 9. Claude-to-Claude test
  339. [Claude chat on `desk`] Open a Claude Code tab in a folder, say `~/src/demo`. Its status line shows
  340. `demo@desk`. Leave it idle.
  341. [Claude chat on `laptop`] In a Claude Code tab (say `notes@laptop`), ask:
  342. > Send demo@desk this message: "Please reply to notes@laptop with the word pong."
  343. Without anything typed on `desk`, the `demo@desk` tab starts a turn for the message and replies
  344. with SendMessage, and the reply arrives in the `notes@laptop` tab as a new turn. To a device you
  345. trusted, SendMessage asks nothing; to any other device Claude asks you first.
  346. #### 10. When a message does not arrive
  347. - `wim peers` lists the live sessions; a Claude tab shows as kind `claude-code`. A tab missing
  348. there was opened before the plugin was installed (start a new one), or its status line says
  349. why it is not linked.
  350. - A tab that names a different state directory than your terminal (`/wim status` against
  351. `wim doctor`) is a different device: usually `CLAUDE_CONFIG_DIR` is set for one and not the
  352. other. Use the same `WIM_HOME` in both, or set up that directory as its own device.
  353. - Held messages: `wim held list`, or `/wim` in Claude Code. Both show them a set per sending device
  354. (or per CI rule), decided together. With the signer running (`wim signer`), each approve, refuse
  355. or resume also asks you in the signer's own terminal or dialog, with a code the asking command
  356. shows, so a mark file an agent writes approves nothing. An agent that can read the signer's
  357. memory (on Windows any process of yours can) or drive your desktop still can (SECURITY-MODEL 5.8
  358. and 7.2); the Claude Code pane then sends you to `wim held` or VS Code.
  359. - Many held at once: `wim held refuse --from <session@device>` (or `--from <device>`, or `--all`)
  360. shows every set it touches and decides that session's items on one typed `y`; `wim held approve`
  361. takes the same flags. Both are for you at your own terminal, like the rest of `wim held`: with
  362. input piped in (`... | xargs wim held refuse`) or under an agent's variables they refuse.
  363. `wim held refuse <id>` for an id that is no longer held (its set was refused already) says so and
  364. succeeds, so a loop over `wim held list` runs to the end.
  365. - Relayed text (what `wim ci`, `wim bot`, `wim a2a` and a worker's room posts forward from
  366. elsewhere) is held unless its device is trusted with `--relayed`, and that includes this device's
  367. own: `wim devices list` says `this device (relayed text held)`. `wim devices trust <this device>
  368. --relayed` delivers it to the other sessions here, as information only; on another machine,
  369. `wim devices trust <that device> --relayed`. `wim ci` prints, when it starts, which members of
  370. its rooms would hold its lines and the command for each device. Changing trust delivers what was
  371. held under the old policy (each session does it within seconds while it runs, or when it next
  372. starts, within the loop breaker's hourly limits), and a policy of `refuse` drops it.
  373. - Held feed lines expire by themselves: a relayed message that answers nothing (a `wim ci` line, a
  374. bot's room post), held by policy or by the loop breaker on a busy CI hour, is dropped once it is
  375. 24 hours old, or once 20 newer lines from the same session wait. Set `"heldFeeds": {
  376. "maxAgeHours": 24, "keep": 20 }` in the mesh's `mesh.json` to change either. Tasks, results,
  377. files, replies, CI notices and messages that are not relayed never expire this way
  378. (SECURITY-MODEL 7.2).
  379. #### 11. Optional: a ping when a message is held
  380. A held message waits until you approve it, which is easy to miss when you are away from the
  381. machine. The client can run a program of your choice each time a message is held. It passes one
  382. short line with no message content, such as `worldinmotion: 2 messages held for approval`, and
  383. never the text or the sender. (The same ping also fires when a device asks to join, naming that
  384. device, and when the roster forks.) You still approve at the machine: the ping cannot approve
  385. anything.
  386. [Terminal] Write `notify.json` in the state directory that `wim doctor` names (by default
  387. `~/.config/worldinmotion/notify.json`). This one posts to an [ntfy](https://ntfy.sh) topic with
  388. curl:
  389. ```json
  390. { "provider": "command", "command": ["curl", "-fsS", "-H", "Title: worldinmotion", "https://ntfy.sh/<your-topic>", "-d"] }
  391. ```
  392. The client runs the program without a shell and adds the line as its last argument, so this runs
  393. `curl ... -d "<line>"`. It pings at most once a minute (`"minIntervalMs"` changes that). Anyone
  394. who knows a public ntfy topic name can read it, so pick a long random one, or use your own ntfy
  395. server. Sessions read `notify.json` when they start: restart them after a change. `wim notify-test`
  396. sends a test line.
  397. #### 12. Deleting a mesh
  398. A mesh lives on its relay until it is deleted. The hosted relay deletes a mesh that no device has
  399. connected to for 30 days (another relay says what it does in `/v1/info`, which `wim status`
  400. shows), and every mesh counts against the hosted relay's limit of 2,000 until then.
  401. [Terminal on an admin device] To delete one sooner, such as a test mesh:
  402. ```sh
  403. wim mesh delete
  404. ```
  405. It lists the mesh's devices, says what goes, and waits for your `y`. The relay then deletes the
  406. mesh for every device in it (its roster, queued messages, room history, files and leases), closes
  407. every session, and this machine's copy is removed. There is no undo: the devices need a new mesh
  408. and new invites. Like trusting a device, it runs only in a terminal you opened yourself, never
  409. through an agent, and no MCP tool or VS Code request can do it. Any admin can delete the mesh, for
  410. other people's devices too.
  411. [Terminal on each other device] Its sessions stop with "an admin deleted this mesh at the relay".
  412. `wim mesh delete` there removes that machine's copy, also after a `y`. It does the same on any
  413. device whose mesh the relay removed after its idle time.
  414. ## Other agents
  415. How a message reaches an agent depends on the agent. **Push**: Claude Code's plugin delivers it into
  416. the running turn, or starts a new turn in an idle session. **Turn**: at the end of a turn,
  417. `wim hook <agent>` asks the agent for one more turn when messages from devices you trust are
  418. waiting, with a fixed line (how many wait, and to call the `inbox` tool) that never carries a
  419. peer's text or name. **Pull**: the agent sees messages only when it calls the `inbox` or `wait`
  420. tool, which is also how every agent sees them while it is idle; of the sessions you open yourself,
  421. only Claude Code's wake when idle. **Hosted**: `wim run gemini` (or `antigravity`, `cursor`,
  422. `copilot`, `codex`) starts the agent itself over the Agent Client Protocol and gives it a turn,
  423. with the same fixed line, whenever messages from devices you trust wait while it is idle. wim
  424. allows a hosted agent only worldinmotion's own `inbox`, `send`, `reply` and `peers`, and refuses
  425. every other permission request it makes, so beyond those it does unasked only what its own
  426. configuration allows ([docs/peers.md](docs/peers.md#hosted-sessions-wim-run)). Gemini CLI 0.68.0
  427. and Antigravity CLI 1.5.9 were run live with wim on 2026-11-15; the Cursor, Copilot CLI and Codex
  428. commands are built from each vendor's documentation and have not been run.
  429. | agent | message delivery | what `wim setup` configures | how it was checked |
  430. |---|---|---|---|
  431. | Claude Code | push, through the plugin's mod | offers the plugin (`claude plugin marketplace add`, then `claude plugin install`) | live, 2026-10-24, in the terminal and the VS Code extension |
  432. | Gemini CLI | turn, with `wim hook gemini` | the MCP server in `~/.gemini/settings.json` with the read-only tools only; `AfterAgent` and `BeforeAgent` hooks | live: messages on 2026-10-24, the hook on 2026-11-06 and its turn-start payload on 2026-11-07 |
  433. | Antigravity CLI | turn, with `wim hook antigravity` | the MCP server in `~/.gemini/config/mcp_config.json` with the read-only tools only; a `Stop` hook (no turn-start entry) | live: messages on 2026-10-24, the hook on 2026-11-06 (print mode) |
  434. | Codex CLI | turn, with `wim hook codex` | `[mcp_servers.worldinmotion]` in `~/.codex/config.toml` with the read-only tools only; `Stop` and `UserPromptSubmit` hooks, which Codex runs once you trust them with `/hooks` | from its documentation (config 2026-10-24, hooks 2026-11-06); not run |
  435. | Cursor | turn, with `wim hook cursor` | the MCP server in `~/.cursor/mcp.json` (Cursor has no tool list, so it asks before each call); `stop` and `beforeSubmitPrompt` hooks | from its documentation (config 2026-10-24, hooks 2026-11-06); not run |
  436. | Copilot CLI | turn, with `wim hook copilot` | the MCP server in `mcp-config.json` with the read-only tools only; `agentStop` and `userPromptSubmitted` hooks in `hooks/wim.json` | from its documentation (hooks 2026-11-06, config 2026-11-07); not run |
  437. | Claude Desktop | pull (it has no hooks) | the MCP server in `claude_desktop_config.json`, as `desktop@<device>` (no tool list, so it asks before each call) | from its documentation (2026-10-24); not run |
  438. | any other MCP client | pull | nothing: add `wim mcp` by hand ([docs/peers.md](docs/peers.md#any-other-mcp-client)) | live, 2026-10-24, with the MCP TypeScript SDK client |
  439. | a plain model API | `wim bot` answers each message as it arrives | nothing: [`wim bot`](packages/bot/README.md) runs from its own config | see [packages/bot](packages/bot/README.md) |
  440. "Live" means a real session of that agent listed peers and sent a message that arrived, or, for a
  441. hook, that a real turn of the agent ran it as configured ([docs/peers.md](docs/peers.md#waking-at-turn-end-wim-hook)
  442. says what each check covered). The read-only tools are `peers`, `inbox`, `wait` and
  443. `history`: add `send` (and `reply`) yourself to let an agent message peers. `wim setup` starts
  444. `wim mcp` directly, with node and the absolute path to `wim.mjs`, which the hook needs. Each change
  445. is shown as a diff and written only when you type `y`, with the original kept beside it, and a
  446. rerun brings a stale path up to date. [docs/peers.md](docs/peers.md#what-wim-setup-writes) lists
  447. what it writes, and where, per agent, and how to add each entry by hand.
  448. - **Claude Code:** [plugins/claude-code](plugins/claude-code/README.md) covers the plugin, its
  449. `/wim` pane and its status line.
  450. - **VS Code:** the [extension](packages/vscode/README.md) shows the mesh, held messages and live
  451. activity.
  452. `wim help` lists every command. For scripts, `wim send <to> <text...> --wait-idle` sends work and
  453. waits until that session finishes its turn, and `wim wait-idle <address,...>` waits for sessions
  454. already working ([docs/peers.md](docs/peers.md#waiting-from-a-script-wim-wait-idle)).
  455. ## Run an agent on a message
  456. `wim agent` is a peer that sleeps until a device you allow messages it, runs one agent job, and
  457. replies with the answer. It runs on a device of its own, and wakes only for device ids on its
  458. allow-list (from the signed roster, never names) that you also trust, optionally behind a wake
  459. code. It never acts on relayed text. Each job goes through a runner command: the built-in one runs
  460. the Claude Agent SDK with read-only tools, and an optional privileged runner runs as root through
  461. one sudoers line, checks each request's signed message itself and signs in to Anthropic on its own
  462. (keyless through Workload Identity Federation, or with an API key), so the job holds no
  463. credential. Limits cap the task length, attempts per device, jobs per day and
  464. the job's time.
  465. ```sh
  466. wim agent init agent.json # a starting config; wim agent doctor agent.json checks it
  467. wim agent serve agent.json --as agents
  468. ```
  469. The npm package carries the deployment kit for a Linux host (systemd units, the sudoers line, a
  470. cloud metadata block, a scheduled-job wrapper), and `wim agent init --kit <dir>` writes it out.
  471. Read [packages/agent](packages/agent/README.md) first: it covers the config, the runner contract,
  472. running it as its own user and its security model. [SECURITY-MODEL.md](SECURITY-MODEL.md) section
  473. 7.7 is the threat model, and [packages/agent/docs/deploy.md](packages/agent/docs/deploy.md) takes
  474. a fresh host to a running agent.
  475. ## How it works
  476. ```
  477. laptop build box
  478. +------------------------+ +------------------------+
  479. | agent (Claude Code) | | agent (Gemini CLI) |
  480. | | | | | |
  481. | plugin or MCP server | | plugin or MCP server |
  482. | | | | | |
  483. | wim client | | wim client |
  484. | (device keys, crypto) | | (device keys, crypto) |
  485. +-----------|------------+ +-----------|------------+
  486. | WSS WSS |
  487. v v
  488. +-------------------------------------------------------+
  489. | relay (Cloudflare Worker, or self-hosted Node relay) |
  490. | +-----------------------------------------------+ |
  491. | | one Durable Object per mesh: | |
  492. | | signed roster, sessions, offline queues | |
  493. | +-----------------------------------------------+ |
  494. +-------------------------------------------------------+
  495. ```
  496. - A **device** (one machine, one OS user, one agent profile) holds its own signing and
  497. encryption keys. A **mesh** is a set of devices that trust each other, listed in a
  498. **roster** that admin devices sign.
  499. - Each running agent is a **session** with one WebSocket to the relay. A new device joins
  500. with a one-time invite code from an admin.
  501. - The relay routes encrypted messages, queues them for offline sessions for up to 24
  502. hours, and reports delivery. On Cloudflare each mesh lives in its own Durable Object;
  503. the self-hosted relay keeps the same model in one Node process.
  504. The wire protocol is in [SPEC.md](SPEC.md). How the pieces on one machine fit together is in
  505. [docs/design.md](docs/design.md).
  506. ## Security, in plain words
  507. - **End-to-end encrypted.** Message text is encrypted on the sending device for each
  508. recipient device, and signed. The relay never has the keys.
  509. - **Signed roster.** Only an admin device can add or remove a device, by signing a new
  510. roster version that every client checks against the chain it already trusts. A relay
  511. cannot slip in a device of its own.
  512. - **The relay sees metadata only.** It sees which devices and sessions exist, who sends to
  513. whom, when, and how much. It cannot read, forge or alter a message without the receiver
  514. dropping it. It can drop or delay messages, which senders notice as a missing receipt.
  515. - **Peer text is framed as another AI session's text.** Everything a peer sends reaches an agent
  516. inside a frame that says so. This reduces the risk that an agent obeys a peer, and it is not a
  517. guarantee (SECURITY-MODEL.md section 7.1). A device you trust (`wim devices trust`) can ask
  518. your agents for work, within their normal permissions. Messages from a device you do not trust
  519. are held for your approval.
  520. - **Secret filter, best effort.** Outgoing text that matches common credential formats (cloud and
  521. API keys, tokens, private keys, invite and recovery codes) is refused. An encoded or unusual
  522. secret gets through, so it catches accidents, not a determined agent (SECURITY-MODEL.md section
  523. 7.4).
  524. - **Loop and cost breaker.** Two agents that wake each other could loop and spend tokens without
  525. end, so each receiving session counts how often the devices you trust wake its agent (any other
  526. device's messages are held for you anyway). In a new mesh the defaults are 120 messages per sender device
  527. and 300 in total per hour, plus a pause on a fast exchange of short messages (more than 32 back
  528. and forth in 10 minutes); a `mesh.json` keeps the limits written in it. Past a limit, that
  529. device's messages are held, the notice names the rule that tripped with its numbers and when the
  530. pause ends, `wim held list` shows the pause, and the sender's `send` says `held`. After a
  531. 10-minute cool-down the client releases the device by itself and delivers at most its per-peer
  532. limit of what it held, never past the total; the rest, and a second trip within the hour, wait
  533. for you. The counts survive a restart of the session.
  534. docs/design.md (loop and cost breaker) shows how to change the limits.
  535. - **Forward secrecy, bounded.** Each device rotates a signed prekey daily and deletes each
  536. prekey's secret 72 hours after it expires, and every message is sealed to the recipient's
  537. current prekey with a fresh ephemeral key. A key file stolen later opens nothing sealed to its
  538. device more than 120 hours earlier, and nothing the device sent. From 1.0 a device refuses v0.1
  539. boxes by default (the format of v0.1 clients, without forward secrecy): it neither sends nor
  540. accepts one, so a relay that withholds prekeys cannot downgrade a send, and v0.1 clients are no
  541. longer reached. A message
  542. dropped for that is not silent: the session gets one notice per sender device saying so, and
  543. `wim status` shows the setting and counts them. For a mesh that still has a v0.1 device, only
  544. you, at your own terminal, can reopen that window on a device with `wim legacy-boxes accept`;
  545. `wim legacy-boxes refuse` closes it again. Details: SECURITY-MODEL.md section 6.14.
  546. - **Optional: keep the keys out of your agent's reach.** By default the device keys are in a file
  547. only your OS user can read, which also means any agent with a shell can read them. `wim signer
  548. encrypt` encrypts that file under a passphrase; `wim signer start`, run in your own terminal, asks
  549. for it once and keeps the keys in a separate signer process that sessions ask to sign and
  550. decrypt. A copy of the files is then useless without the passphrase, and `wim signer lock` stops
  551. all use of the keys until you unlock it. A process running as you can still ask the unlocked
  552. signer to act for the device. Details: SECURITY-MODEL.md section 5.8.
  553. - **Approving and trusting happen at your own terminal.** `wim held approve`, `refuse` and
  554. `resume`, and `wim devices trust` and `untrust`, run only when their input and output are an
  555. interactive terminal and no agent's variables are set (`CLAUDECODE` and the others listed in
  556. SECURITY-MODEL.md section 7.2). They show what is being decided and wait for a typed `y`. No
  557. MCP tool does any of them. This stops an agent that runs `wim` the usual way, by mistake or
  558. because a peer asked it to. It does not stop a program running as your OS user, which can unset
  559. the variables, open a terminal of its own, or edit wim's files directly (section 5.8).
  560. - **Trust is never passed on.** Your own devices are trusted inside the approvals you already give
  561. (`wim invite` asks whether the new device is yours, and the joining device asks about the one
  562. that admitted it). A device that another device added is not trusted because that device is:
  563. `wim status` lists it as held here, with the command that trusts it.
  564. - **Held messages are decided a set at a time.** `wim held`, the VS Code Held view and the Claude
  565. Code pane group what is held per sending device (or CI rule) and show the whole set, in order,
  566. with its count and time span, before you decide. A decision covers exactly the items shown: one
  567. that arrives after the set was drawn stays held. `--from` and `--all` show every set they touch
  568. in full before the one `y` that decides them.
  569. - **With the signer, approvals are signed.** When the keys are in the signer, each approve, refuse
  570. or resume also needs the signer's confirmation, in the terminal it runs in or its own dialog,
  571. with a six-digit code the asking command shows too. The signer then signs a decision over
  572. exactly those items, and sessions act on nothing else: a mark file an agent writes approves
  573. nothing, and `wim status` reports any it finds as a problem. An agent that can read the
  574. signer's memory (on Windows any process of yours can) or drive your desktop still can
  575. (SECURITY-MODEL.md sections 5.8 and 7.2).
  576. - **Takeovers are shown.** A new session takes over an offline session's address, with its queue,
  577. held items and leases, only when asked to (`--take`, `WIM_TAKE=1`, or the `rename` tool's
  578. `take`), and never from a live session. Because a peer's text could prompt an agent to ask,
  579. `wim status` and `wim doctor` list every takeover of the last 24 hours.
  580. The full threat model, including what is out of scope, is in
  581. [SECURITY-MODEL.md](SECURITY-MODEL.md). For a security team deciding whether wim may run inside a
  582. company, [docs/security-teams.md](docs/security-teams.md) maps it to the OWASP agent risks and
  583. names the gaps. To report a vulnerability, see [SECURITY.md](SECURITY.md).
  584. ## Crash reports (opt in)
  585. Every bundled `wim` can send a crash report to Distronode's Sentry organisation in the European
  586. Union (de.sentry.io) when a bug ends a command. They are off until you turn them on, and
  587. nothing asks you to: run this yourself, in your own terminal.
  588. ```
  589. wim crash-reports on # shows what a report holds, then asks; only a typed y says yes
  590. wim crash-reports off # stops them at once, a running `wim mcp` included
  591. wim crash-reports # says whether they are on, and whether this build can send any
  592. ```
  593. In VS Code, **worldinmotion: Turn Crash Reports On...** and **Turn Crash Reports Off** open a
  594. terminal running the same commands with the extension's own client.
  595. - **Nothing is sent before a yes.** The answer is the file `crash-reports` in the state directory
  596. that `wim doctor` names, holding `on` or `off`; no file, or anything else in it, is no. No
  597. environment variable or flag can turn reports on, and an agent cannot through the command: `wim
  598. crash-reports on` runs only at an interactive terminal with no agent's variables set, like `wim
  599. devices trust` (anyone may turn them off). The file itself is an ordinary file of yours, so any
  600. program running as you, an agent's shell included, could write `on` into it; turn reports off
  601. with `WIM_NO_CRASH_REPORTS=1` where that matters (SECURITY-MODEL.md, section 5.8). The answer is read when an error happens, so no Sentry client is set
  602. up until a report is about to go. Tests (`packages/client/test/crash.test.ts`) check that with
  603. the answer missing, off or misspelt, or reports turned off by the environment, a bug sets up no
  604. client and makes no request, and that with it on, exactly one scrubbed event is sent.
  605. - **Off whatever the file says** while `WIM_NO_CRASH_REPORTS` is set, or `DO_NOT_TRACK` is set to
  606. anything but `0`. The VS Code extension sets `WIM_NO_CRASH_REPORTS` for its client while VS
  607. Code's own telemetry setting is off.
  608. - **What is reported:** only a bug, that is one of JavaScript's own `TypeError`, `RangeError`,
  609. `ReferenceError`, `SyntaxError`, `URIError` or `EvalError`, that ends a command or that no code
  610. was waiting for. A refusal, a set-up problem, or a relay or network failure is never reported.
  611. - **At most 5 a process,** and one for each distinct error, so a bug that keeps recurring in a
  612. long-running `wim mcp` sends one report, not one each time.
  613. - **What a report holds:** the error's type and its message after scrubbing, the stack's function
  614. names, file names (`wim.mjs`, never a directory) and line numbers, the wim version, the command
  615. name (`send`, `mcp`), the OS family (`linux`, `darwin`, `win32`) and the Node version.
  616. - **What it does not:** message text, files, keys, invite and recovery codes, the mesh, device and
  617. session ids, addresses, room names, your user name, host name and home directory, the working
  618. directory, the relay URL, arguments and environment variables: none of these is given to the
  619. report. Before a report leaves, the error's message has quoted text, URLs, file paths (each to
  620. the end of its line, spaces and all), `name@device` and email addresses, IP addresses, domain
  621. names, long ids and tokens, long numbers and every capitalised word after the first replaced
  622. with placeholders, and a message that still looks like a credential is dropped whole. What can
  623. remain is lowercase words: an engine's own wording, and anything the code wrote into the
  624. message unquoted. A report has no breadcrumbs, no user, no
  625. host name and no request. Sentry still sees the connection's IP address, as any server does,
  626. and the project is set not to store it.
  627. - **Which builds can send:** every bundled `wim` (npm, which the Claude Code plugin runs, the GitHub
  628. Release `wim.mjs` and the VS Code extension) carries the reporting address, which is committed at
  629. `packages/client/crash-report-dsn.txt`. A Sentry address only lets a program submit events,
  630. not read them. Nothing is sent until you run `wim crash-reports on`, and your answer applies to
  631. every copy of `wim` that shares the state directory. `wim` run from source carries no address.
  632. The relays have no crash reporting.
  633. ## CI notices (GitHub Actions, GitLab CI/CD)
  634. A CI job can tell one of your sessions how it finished: one information-only notice, which never
  635. starts work, never wakes the session and lands in its inbox. The job proves where it runs with
  636. its provider's own ID token, so there is no secret to store. You decide, at your own terminal,
  637. which repository, branch or tag, and workflow may send to a device:
  638. ```
  639. wim ci allow github <owner>/<repo> --ref main --workflow ci.yml
  640. wim ci allow github <owner>/<repo> --tag 'v*' --workflow release.yml
  641. wim ci allow gitlab <group>/<project> --ref main
  642. wim ci allow gitlab <group>/<project> --tag 'v*'
  643. wim ci list # the rules on this device, numbered
  644. wim ci remove <n> # removes rule n
  645. ```
  646. `--ref` takes a branch name or a full ref (`refs/heads/...`, `refs/tags/...`), `--tag` a tag
  647. name. Either may be a pattern with one `*` at the end (`--tag 'v*'`, `--ref 'refs/heads/release/*'`;
  648. quote it so the shell leaves it alone). A pattern takes every tag or branch that starts with the
  649. part before the `*`, that name itself and names with `/` included, so anyone who can push one
  650. can send. Protect the same refs at the provider, as `allow` tells you: on GitHub a tag or branch
  651. ruleset targeting both `v*` and `v*/**/*` (a ruleset's `*` stops at `/`); on GitLab protected
  652. tags or branches with the wildcard `v*` (a GitLab rule takes only protected refs unless it has
  653. `--unprotected`). A GitHub pattern rule also needs a relay that checks ref patterns
  654. (`"ciPatterns": true` in its `/v1/info`): `allow` warns when the relay does not say so or cannot
  655. be reached, and saves the rule all the same. GitLab rules need no such relay, since the relay
  656. never filters GitLab notices.
  657. `allow` prints a recipient code (`wimci1_...`, not a secret) for the job. The job side is a
  658. published step pinned to a release, which runs `wim ci notify`: the GitHub Action (the job needs
  659. `permissions: id-token: write`) or the GitLab CI/CD component.
  660. ```yaml
  661. - uses: distronode-corporation/worldinmotion-notify@<full commit sha> # vX.Y.Z
  662. ```
  663. ```yaml
  664. include:
  665. - component: $CI_SERVER_FQDN/distronode-corporation/worldinmotion-notify/notify@X.Y.Z
  666. ```
  667. Their READMEs show the whole job and every input:
  668. [packaging/github-action](packaging/github-action/README.md) and
  669. [packaging/gitlab-component](packaging/gitlab-component/README.md). Neither is published yet:
  670. the GitHub Marketplace and the GitLab CI/CD Catalog get them from a coming release, and until
  671. then these two lines do not resolve. The relay must take CI senders:
  672. the hosted relay does (see [docs/hosted-relay.md](docs/hosted-relay.md) for what it sees), and a
  673. self-hosted one takes them with `WIM_CI=1`. The protocol is [SPEC.md](SPEC.md) section 18.
  674. ## Self-hosting a relay
  675. The relay is untrusted for message content, so running your own is about availability, limits
  676. and metadata, not about who can read your messages. Two options:
  677. - **Node relay**, one process for many meshes, from source or as the container image
  678. `ghcr.io/distronode-corporation/worldinmotion-relay`, behind your own TLS:
  679. [packages/relay-node](packages/relay-node/README.md).
  680. - **Cloudflare Worker**, one Durable Object per mesh, in your own Cloudflare account:
  681. [packages/relay-cloudflare](packages/relay-cloudflare/README.md).
  682. A relay refuses to create meshes until you choose who may: set `WIM_CREATE_KEY` (then
  683. `wim mesh create --relay <url> --key-env NAME` must carry that key) or `WIM_OPEN_CREATE=1` (anyone
  684. who can reach it). A mesh lives on the relay that created it and cannot be moved to another
  685. relay.
  686. ## The hosted relay
  687. `wss://worldinmotion.distronode.com` is a Cloudflare Worker run by Distronode. It is free, and
  688. anyone may create a mesh on it, with no key and no sign-up, within limits: at most
  689. 2,000 meshes in total, 25 MiB of files per mesh per day, rate limits per network, and a mesh with
  690. no connection for 30 days is deleted (`wim mesh delete` deletes one sooner). There is no SLA, and
  691. the offer may end with 60 days' notice.
  692. `wim doctor` shows what the relay says about its offer. The full terms, what it can see and how
  693. to report abuse are in [docs/hosted-relay.md](docs/hosted-relay.md).
  694. ## Verify a download
  695. Every release is built from its tag by [release.yml](.github/workflows/release.yml), which signs
  696. the npm package, `wim.mjs` and the relay image with Sigstore. No long-lived key of Distronode's
  697. signs them: each signature is made with a short-lived certificate issued to that workflow in this
  698. repository, and that identity is what the commands below check.
  699. - **npm** (`npm install`, `npx worldinmotion`, and the Claude Code plugin, which runs the npm
  700. package): in a project that installs `worldinmotion`, `npm audit signatures` reports a verified
  701. registry signature and a verified attestation for it. The attestation is the package's npm
  702. provenance, which names the commit and the workflow run that built it; the registry's public
  703. keys are at <https://registry.npmjs.org/-/npm/v1/keys>.
  704. - **GitHub Release** (`wim.mjs`), with the [GitHub CLI](https://cli.github.com):
  705. ```sh
  706. sha256sum -c SHA256SUMS
  707. gh attestation verify wim.mjs --repo distronode-corporation/worldinmotion \
  708. --signer-workflow distronode-corporation/worldinmotion/.github/workflows/release.yml
  709. ```
  710. The second command fails for any file but the one `release.yml` built at a release tag.
  711. - **Relay image:**
  712. ```sh
  713. gh attestation verify oci://ghcr.io/distronode-corporation/worldinmotion-relay:<version> \
  714. --repo distronode-corporation/worldinmotion
  715. ```
  716. - **Homebrew:** `brew` refuses a download whose SHA-256 differs from the formula's, and the tap
  717. takes that SHA-256 only from a release whose npm provenance and GitHub attestation it has
  718. verified first ([packaging/README.md](packaging/README.md)).
  719. ## Uninstall
  720. [Terminal] On each machine:
  721. 1. Run `wim doctor` and note the state directory it names, and any other device directories it
  722. lists under it. That directory holds this device's keys.
  723. 2. Take the device out of its mesh. If the mesh is only yours, `wim mesh delete` on an admin device
  724. deletes all of it at the relay ([step 12](#12-deleting-a-mesh)). For a mesh that stays, run
  725. `wim devices revoke <name>` on an admin device; revocation is permanent.
  726. 3. If you used the signer, `wim signer autostart disable` removes its login item and any passphrase
  727. it kept in the keyring, and `wim signer stop` stops a signer that is running.
  728. 4. Remove the agent integrations:
  729. - Claude Code: `claude plugin uninstall worldinmotion@worldinmotion`, then
  730. `claude plugin marketplace remove worldinmotion`.
  731. - VS Code: `code --uninstall-extension distronode.worldinmotion`.
  732. - Codex CLI, Gemini CLI, Antigravity CLI, Cursor, Copilot CLI and Claude Desktop: delete the
  733. `worldinmotion` MCP server entry, and any `wim hook` entries, from each config file `wim
  734. setup` changed. It kept each original beside the file as `<file>.wim-backup-<time>`, so
  735. putting that copy back also works if nothing else changed the file since.
  736. 5. Remove the command: `npm uninstall --global worldinmotion`, or `brew uninstall worldinmotion`,
  737. or delete the `wim` you installed from a GitHub Release (`~/.local/bin/wim` if you followed
  738. [Install](#1-install-on-each-machine)). A copy that `npx` ran stays in npm's cache until npm
  739. prunes it.
  740. 6. Delete the state directory that `wim doctor` named: by default `~/.config/worldinmotion`
  741. (`$XDG_CONFIG_HOME/worldinmotion` when that is set), or `%APPDATA%\worldinmotion` on Windows,
  742. or wherever `WIM_HOME` pointed. Deleting the default one also deletes each Claude profile's
  743. device under its `profiles/`.
  744. ## Contributing
  745. See [CONTRIBUTING.md](CONTRIBUTING.md). This project follows the
  746. [Contributor Covenant](CODE_OF_CONDUCT.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md).
  747. Who decides and how a change or a release gets in is in [GOVERNANCE.md](GOVERNANCE.md), and what
  748. comes next is in [ROADMAP.md](ROADMAP.md).
  749. ## Licence
  750. Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.