# world2agent: a private schema package, no source directory, and three runtimes that each want a restart

> An open protocol for what agents perceive, delivered as npm packages called sensors. What the repository actually contains is a versioned JSON schema, a validator, nine documents and one skill, with no implementation and a single npm package marked private. The install paths are where the design shows: three agent runtimes, three different shapes, two gateway restarts, one config file rewritten in place, and a trust warning that arrives after the first third-party sensor example.

**machinepulse-ai/world2agent** — World2Agent(W2A) is an open protocol that standardizes how Al agents perceive the real world.

- Repository: https://github.com/machinepulse-ai/world2agent
- Website: https://world2agent.ai
- Stars: 1,133 · Forks: 41
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/machinepulse-ai-world2agent

## The protocol's only npm package is private and exports nothing

There is one `package.json` at the root and it is not something you can install. It is named `@world2agent/protocol`, it carries `"private": true`, and its version is 0.1.0. Its description says it is the canonical schema, the wire format. Beyond that it has almost no surface: no `main`, no `exports`, no `bin`, and no `dependencies` at all, only three dev dependencies for schema generation and validation. So the protocol is not distributed as a package. It is a specification that lives in this repository as files, and the things that are actually installed are sensors, which are separate npm packages published by other people. That distinction is the whole architecture in one manifest, and it also explains why the README's own discovery instruction falls back to a plain npm search for the sensor naming prefix when you would rather not use the hosted catalog. One consequence is that the protocol version exists in two unreconciled places. The private manifest says 0.1.0, and the only other version marker anywhere in the tree is the directory name the schema is generated into, while the README itself states no protocol version at all. A sensor author therefore has no single declared version to target.

## Schema generation is the build, and extra properties are permitted

There are two scripts and one of them is the entire build. The first compiles every exported type in a versioned subdirectory into a JSON schema:

```
typescript-json-schema schema/0.1/tsconfig.json '*' --out schema/0.1/schema.json --required --strictNullChecks --topRef --noExtraProps=false
```

Three things in that line matter. The TypeScript configuration lives under a directory named for the protocol version, so the schema is versioned in its path rather than by a tag. The `--noExtraProps=false` flag means the generated schema does not forbid additional properties, which is a deliberate choice for forward compatibility and also means a sensor may send fields the validator accepts and no consumer reads. The second script validates the example payloads against that schema, using the JSON Schema validator and its format add-on as dev dependencies, so nothing is added to what a consumer installs. Both scripts are the whole of the continuous integration surface, which is appropriate for a repository whose contribution is a contract rather than code. The practical effect for a sensor author is that validation is something you arrange for yourself: the validator and its format add-on live in this repository's dev dependencies, so validating a payload outside continuous integration means installing your own. The prose specification of the same contract is a separate document again, in a signal format spec alongside an architecture deep dive.

## Three runtimes, three install shapes, two restarts and one rewritten config

The quick start covers three agent runtimes and none of them installs the same way. Claude Code takes three slash commands inside an active session, to add a plugin marketplace, install the plugin, and reload plugins, and then it requires you to quit and relaunch the editor with a flag that is named for being dangerous, so that a development channel loads and signals flow into the session. Hermes takes a global install of a bridge package plus a skills install, and on first use the agent asks you to restart the Hermes gateway once after it enables the webhook platform. OpenClaw takes a global bridge install plus a skills install, and on first use the bridge writes a managed hooks block into a JSON config file in your home directory, generating a token if one is absent, asking you to restart its gateway, and keeping a timestamped backup of the original file beside it. Each restart exists for a different reason, which is worth separating before you debug one. The Claude relaunch is needed so the development channel is loaded and signals can flow into the session at all. The Hermes restart is needed once, after the webhook platform has been enabled. The OpenClaw restart is needed because a managed hooks block has been written into your config and will not take effect until the gateway re-reads it.

## Two of the three runtimes accept a sentence as the install command

The OpenClaw route has no command at all for the actual install. You are told to send this in a chat window:

```
Use world2agent-manage skill install @quill-io/sensor-frontier-ai-news
```

The Hermes route offers the same choice, letting you describe the intent in natural language or use the slash form. What the agent then does is spelled out, and it is a lot: it handles the package install, answers questions from a setup document, subscribes a webhook and starts a subprocess. In the OpenClaw case the skill walks the same setup questions, generates a handler skill, registers the sensor and starts a supervisor. So on two of three runtimes the thing you are installing installs itself, using an account that already has permission to run package installs and start background processes on your machine. That is a larger trust decision than typing a command you can read first, and it is worth weighing against the same README's advice to review a sensor's code before installing it. It also tells you the shape of the signal path. In the Hermes case the agent handles subprocess startup, so a running child process is what delivers signals, and in the OpenClaw case a supervisor is the long-lived half that the skill starts. Neither is documented further in the README, which means the process model is something you learn from the bridge package rather than from the protocol documentation.

## Every runtime plugin is served from a different repository

The README says W2A ships with native plugins for Claude Code, Hermes and OpenClaw, and then each instruction points somewhere else. The Claude Code path adds a marketplace named for a separate repository and installs the plugin from it. The Hermes path installs a bridge package from npm and then pulls a skill from a subdirectory of that same separate repository. The OpenClaw path uses its own bridge package and a skills install by name. What this repository holds is the schema, the validation script, the documentation directory, a skills directory and continuous integration configuration. There is no source directory at the root and no runtime code of its own. That is a coherent split for a protocol, and it also means that when a runtime integration breaks, the fix belongs in the other repository, and that the version of the protocol you have and the version of the plugin you installed are two independent numbers that nothing in either manifest appears to tie together. There is a fourth path for people who are not using any of the three runtimes: the quick start document carries an anchor for a second option covering code, an SDK and a sensor, which implies a first option that is the plugin route described above. The README points readers integrating W2A into their own agent system at exactly that second option.

## A multi-sensor guide exists for a feature the roadmap lists as future

The roadmap has one item on it. A graph layer, described as composing and enriching signals from multiple sensors before they reach your agent, with a link to a request for comments. That is future work, and it is the layer that would decide how two sensors disagree. Yet the documentation set already includes a multi-sensor guide among its nine documents, alongside why the protocol exists, the signal format specification, an architecture deep dive, a quick start with an SDK option, the catalog guide, a build-a-sensor guide and a contributing guide. So the documentation describes working with several sensors today while the composition and enrichment step is still proposed. The pragmatic reading is that multi-sensor today means several independent streams arriving at one agent, and that merging, filtering or arbitrating between them is what the roadmap item would add. Plan your integration on that basis rather than assuming the guide documents a merge layer that does not exist yet. The catalog itself is organised the same way, by what a sensor perceives rather than by who wrote it, with categories given as markets, news, production alerts, weather and AI labs. So the taxonomy a user browses is perceptual, and the taxonomy the roadmap proposes for combining streams is a separate axis that does not yet appear in it.

## The first sensor example installs from an unrelated npm organisation

After the Claude Code plugin is installed, the README offers two example sensors, and they come from different publishers. One is scoped to the protocol's own organisation, and the other is scoped to an organisation with no visible relationship to it. Both are installed with the same slash command, differing only in the package name. That is an honest illustration of the point the README makes a few paragraphs later, that an untrusted sensor is effectively an untrusted instruction source, but the ordering works against the warning: the reader has already been invited to install a third-party package, and has been told to relaunch their editor with a development-channel flag, before they reach the sentence telling them to review the code first. The security note is set as a block quote immediately after the catalog link at the end of the quick start, which is the furthest point from the install commands in the document. The note itself gives two instructions rather than one: prefer open-source sensors from authors you trust, and read the code before you install it.

## A star badge is left commented out with a note to uncomment after launch

Two small things in the file are worth recording because they show the state of the project. Near the community links there is a commented-out star history badge with an inline note reading that it should be uncommented after launch, which means the README is published before the point its author considered launch. And the community block points at a website, a social account, a video channel and a chat server, all four operated by the same organisation that built the protocol. Alongside those, the partners section recommends a single hosting provider for deploying your code or agents. The README is explicit that W2A is not a product but an open protocol and an invitation, and the sensors are meant to come from the community. What is worth keeping straight is that the catalog of those community sensors and the channels where releases are announced are both vendor-operated, so the protocol is open in a narrower sense than the framing suggests. The community supply is bootstrapped by a skill rather than by hand: a sensor is described as about fifty lines, the `build-w2a-sensor` skill walks a coding agent through discovery, signal design, scaffolding and the install recipe, it installs from a URL in this repository's own skills directory, and the last step is publishing to npm. The architecture itself is stated in three words, world to sensor to agent, with sensors watching data sources and emitting structured data that follows the protocol.

## Conclusion

Treat this repository as a specification rather than as a library, and read it as one. The canonical artefact is a versioned JSON schema generated from TypeScript types, with examples validated in continuous integration, and a skill that walks a coding agent through writing a sensor in roughly fifty lines. That is a coherent and unusually disciplined shape for a protocol at version 0.1. Four things to settle before you build on it. The schema is generated with additional properties permitted, so a sensor can send fields the validator accepts and ignores; if you care about strictness you have to tighten that yourself. Every runtime plugin is served from a different repository, so this one is not where the integration code lives. Composition across sensors is listed on the roadmap as future work even though a multi-sensor guide already exists, so plan for one sensor at a time. And read the trust warning before you install anything, because a sensor's signals drive what your agent perceives and does, which makes an unreviewed package an instruction source. If you need a perception layer you control end to end today, this is early enough that you may be the one writing the sensor.

## FAQ

### How do I install a World2Agent sensor?

It depends on the runtime. Claude Code adds a plugin marketplace, installs the plugin and reloads plugins in-session, then relaunches with `claude --dangerously-load-development-channels plugin:world2agent@world2agent-plugins`. Hermes and OpenClaw each take a global bridge install plus a skills install, and both require one gateway restart on first use. Sensors are standard npm packages, so `npm search w2a-sensor` also works.

### What does the world2agent repository actually publish to npm?

Nothing installable. Its single package is `@world2agent/protocol` at version 0.1.0 and it is marked private, with no main entry, no exports, no binary and no runtime dependencies, only dev dependencies for schema generation and validation. What is published are sensors, which are separate npm packages written by other authors.

### Does the World2Agent schema reject unknown fields?

No. The schema is generated with `--noExtraProps=false`, so additional properties are not forbidden, which leaves room for a sensor to send fields the validator accepts and no consumer reads. The schema itself is generated from TypeScript types under a versioned `schema/0.1/` directory, and example payloads are validated against it by a second script.

### Is multi-sensor composition supported in World2Agent today?

Several sensors can be installed, and a multi-sensor guide exists among the repository's documents, but the roadmap lists a graph layer for composing and enriching signals from multiple sensors before they reach the agent as future work, with a link to a request for comments on the design.

## Sources

- [Issues](https://github.com/machinepulse-ai/world2agent/issues)
- [License: Apache-2.0](https://github.com/machinepulse-ai/world2agent/blob/main/LICENSE)
- [machinepulse-ai/world2agent on GitHub](https://github.com/machinepulse-ai/world2agent)
- [Project website](https://world2agent.ai)
- [README](https://github.com/machinepulse-ai/world2agent/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/machinepulse-ai-world2agent