Learn

How Buzz plugins work

What a plugin is, what it can access, and how to install, build and check one.

01

What a plugin is

Most of Buzz is built from plugins, including Messages, Agents and Huddles. Plugins you add load the same way.

02

What it can access

A plugin runs inside Buzz as you. It can read what you can read and post as you. Anything it needs outside Buzz has to be declared in its manifest, and Buzz lists it before you install:

Connect to address

HTTPS requests to that address.

Run program

A fixed command on your computer.

Start program

A background program that runs with your account's permissions.

Read your files

Any file your account can read.

Provide tools to local agents

Tools for your agents through Buzz's local MCP server.

Observe and influence agent

Reads what an agent does, and can change or block its actions.

Method and path

Requests to your community's server, signed in as you.

Plugins aren't sandboxed

In Buzz's words, these declarations "describe what the plugin asks Buzz to do. They don't limit what its code can do."

03

Install a plugin

Four steps in Buzz's settings. You need the plugin's Git repository.

Check before you install. Plugins aren't sandboxed: a plugin runs inside Buzz as you and can reach your computer. If you don't know the author, read the source and check the plugin first.

Settings
Plugins
Manage plugins
Open Manage plugins

In Settings, under Plugins.

Add a plugin
Git or GitHub repository
github.com/owner/repo
Branch or tag (optional)
main
Find
Add, paste, Find

Paste the plugin's repository and click Find.

Choose a plugin
Vim mode
Linear
Beeper
Choose a plugin

If the repository has more than one.

Review plugin access
Connect to api.linear.app
Run security
Install plugin
Review, then install

Check what it asks for. Its Enable plugin switch starts on.

Updates are manual. Check for updates, in the plugin's details, pulls the latest code from the same branch or tag and asks you to review its access again.

An "Install in Buzz" link is in review (block/buzz-app #2059). Until it ships, you paste the repository yourself.

04

Build a plugin

Use Buzz's plugin CLI and its examples. Test in a separate community first.

$ buzzodz plugin init
# a folder with manifest.json and plugin.js

$ buzzodz plugin sign
# optional: updates then only come from your key
  • Build buzzodz from the block/buzz-app repository. It doesn't come with the app.
  • Read docs/plugin-architecture.md and examples/plugins/ there.
  • Commit the built plugin.js: Buzz reads committed files and never builds. Leave version out of the manifest.
05

Check a plugin before installing

Check these first, then try the plugin in a test community.

What it declares

Running programs and reading files carry the most risk. The list doesn't limit what the code can do.

Who made it

The author, and where they posted it.

The source

At the commit you'd install: readable code, a license and a README.

Signed or unsigned

A signed plugin only takes updates from the same key.

What it needs from you

API keys or a wallet, and where it keeps them.

Whether anyone reviewed it

Here, Reviewed means a named person read that exact commit. Later updates aren't covered.