Example plugins

Two working plugins, showing the two shapes a Nexa plugin comes in.

	hello	whatsapp
What it adds	a tool, a command, a hook	a chat platform
Written in	plain ESM, no build	TypeScript, against the SDK
Installed as	a folder you copy	a single .nexa file you build
Use it for	developing	distributing

Both are covered by test/plugins/Examples.test.ts, and hello is genuinely discovered, activated in a worker thread and called there, so "copy this folder and it works" is a tested claim rather than a hopeful one.

hello: the development shape

No build step and no dependencies. Copy it and start.

cp -r examples/plugins/hello ~/.nexa/plugins/
NEXA_PLUGINS=1 nexa plugins list

● hello 1.0.0 · user · active
  tools: hello_greet; commands: /hello; hooks: before-turn

Nexa writes ~/.nexa/plugins/hello/config.json from the manifest's configSchema the first time it sees the plugin. Edit it, then:

nexa plugins reload hello     # picks up the edit, and the code, without restarting the daemon
nexa plugins config hello     # what it is reading right now

This is the shape to work in. An edit is a reload rather than a rebuild, and the file you are looking at is the file that runs.

whatsapp: the distribution shape

TypeScript, typed against nexa-plugin, built into one file you can hand to somebody.

cd examples/plugins/whatsapp
npm install
npm run build            # writes whatsapp.nexa
cp whatsapp.nexa ~/.nexa/plugins/

Then fill in ~/.nexa/plugins/whatsapp/config.json, which Nexa writes on the next start, and give it the two secrets its manifest declares:

nexa secrets set whatsapp_token          # a Cloud API access token
nexa secrets set whatsapp_verify_token   # any string; Meta echoes it back during subscription

It needs three things this repository cannot give you: a Meta app with WhatsApp enabled, a phone number id from it, and a public HTTPS URL pointing at the plugin's webhook listener. The plugin binds loopback by default and expects a reverse proxy in front of it, because a channel that opened a public port by default would be an unpleasant surprise on a laptop.

Read the signature note before running it anywhere real. The example does not verify Meta's X-Hub-Signature-256, and the place it belongs is marked in the source. Without it the webhook accepts a message from anyone who finds the URL, and an inbound message is a turn the agent takes with your tools.

What to copy from them

The manifest, mostly. It is strict on purpose, and the two most common ways to get it wrong are both things you can see here:

• contributes is enforcement. Registering a name it does not list is refused, and the refusal discards the whole activation. Every name in either example's code appears in its manifest.
• permissions is what the install prompt shows. hello touches nothing and says so; whatsapp asks for exactly one host and two secret ids. Ask for what you use, because an example copied with an over-broad block becomes a hundred plugins with one.

The rest is in docs/plugins.md and the SDK README.