Skip to content

What plugins can add

A plugin is an object with a name and a setup function. setup returns the parts the plugin adds. Each key in that return value is one part. An unknown key stops startup with a message naming the closest match.

Example files live in examples/. Every example has a test next to it that runs without Discord, and the guide embeds each one. All links in the tables point to the section of the full plugin guide.

Piece What it is for Example Guide
The plugin object Holds the name (lowercase words joined by dashes, unique across plugins) and setup. The plugin itself holds the optional fields: migrations, providers, provides, replaces, requires and preflight. A plugin must add something, or the start stops. tools.ts The plugin object
The context What setup receives: a logger that tags every line with your plugin name, the host environment (locale, time zone), the database, the services, and more. Some fields work only after every plugin is set up. shared-services.ts The context
Part Reach for it when Example Guide
tools You want agents to be able to call something. Each tool names the lowest tier of speaker whose turns may call it. tools.ts tools
holdRules and a tool’s hold A call should wait until the owner approves it in Discord. holds.ts holdRules
prompt You want text added after the core’s prompt in every agent turn. prompt.ts prompt
seeds You want agents created on the first start. Stored agents keep their existing data. seeds.ts seeds
agentSelection Every agent should carry some tools besides its own. selection.ts agentSelection
piPackages Every session should load the Pi extensions of an npm package you installed. List its tools in agentSelection too; roundtable add package writes both. packages.ts piPackages
sessionTools tools cannot express what you need, for example a tool set that changes while the process runs. This is the raw Pi extension form. session-tools.ts sessionTools
toolTiers You use sessionTools and need to say which tier may use each raw tool. none toolTiers
Part Reach for it when Example Guide
events You want to hear what the core does: a service finished starting, a turn started or ended, the team changed, shutdown began. events.ts events
services You need something with a lifetime, such as a timer, a queue, or a connection. Services start after setup and stop in reverse order. services.ts services
migrations Your plugin needs tables of its own. They run before any setup. migrations.ts migrations
preflight A bad setting should stop the start before Discord connects. preflight.ts preflight
backgroundTargets A schedule or a delegated task should come back as a turn of a kind you define, with its own limits. support-desk.ts backgroundTargets
channels Your plugin needs to take over conversations in some channels from the agent server. channels.ts channels
context.observe You want to hear messages in channels other claims own, without admitting or answering them. Direct messages are left out unless you ask, and so are the rooms of a surface that hosts agent rooms unless your filter names that surface. none observe
personas and context.turns You own a kind of conversation, give it a system prompt, and run its turns without writing the typing, stop and reply pipeline. study-room.ts personas
Part Reach for it when Example Guide
Slash commands (commands.add) You want a subcommand under the root command (/roundtable by default). You add it from setup through the DISCORD service. interactions.ts Slash commands
http You want a route on the bot’s listener, such as a health check or a WebSocket endpoint. Anything on it is reachable from the internet, so check a secret in the handler, or a one-time ticket in accept before a WebSocket opens. http.ts http
dashboard You want extra lines on the dashboard message that the agent server keeps pinned in Discord. dashboard.ts dashboard
surfaces You want to connect a chat network other than Discord. A surface reports what people write and posts what conversations answer. fake-surface.ts surfaces
Part Reach for it when Example Guide
providers You want to replace a part the core runs on. There are three slots: judge, images and runtime, and one plugin may fill each. providers.ts providers
The runtime slot You want a runtime other than Pi to run every conversation. echo-runtime.ts The runtime slot
provides and replaces You want to take over a built-in service, such as the schedule store. shared-services.ts Replacing a built-in service

The examples above isolate one plugin capability at a time. These packages show complete implementations of related APIs:

See the official plugin guide for the dice and release-notice copy-in sources. See Services and addons for provides, requires and replaces, and Examples for every example file.