Boongle Plugin API
Build extensions for Boongle IDE with the .bplugin format — a zip package containing a manifest and a Boongle Plugin Script that extends the IDE UI, agent tools, and external integrations.
API highlights: play bundled sounds (boongle.audio), read package assets, open URLs, clipboard, HTTP fetch, IDE events, timers, and native confirm/prompt dialogs.
Overview
| Concept | Description |
|---|---|
.bplugin file |
Zip archive with bplugin.json + main.bplugin (+ optional assets) |
| Marketplace | Published plugins are served from GET /api/plugins/catalog |
| Submission | Upload at /plugins/submit for admin review |
| Runtime | Installed plugins activate in the IDE renderer (Monaco editor font is unaffected) |
Package structure
my-plugin.bplugin (zip)
├── bplugin.json # Manifest (required)
├── main.bplugin # Boongle Plugin Script (required)
├── sounds/ # Optional audio assets (.mp3, .wav, .ogg, …)
├── assets/ # Optional images, fonts, data files
├── icon.png # Optional marketplace icon
└── README.md # Optional docsManifest (bplugin.json)
{
"id": "com.example.hello",
"name": "Hello World",
"version": "1.0.0",
"publisher": "example",
"description": "A demo Boongle plugin.",
"minIdeVersion": "0.1.1",
"main": "main.bplugin",
"contributes": {
"commands": [
{ "id": "hello.say", "title": "Say Hello" }
],
"sidebarPanels": [
{ "id": "hello.panel", "title": "Hello", "icon": "comment" }
],
"agentTools": [
{
"name": "hello_greet",
"description": "Greet someone by name",
"parameters": {
"type": "object",
"properties": {
"name": { "type": "string", "description": "Person to greet" }
},
"required": ["name"]
}
}
],
"integrations": [
{ "id": "slack", "label": "Slack", "description": "Connect Slack workspace" }
],
"settings": [
{ "id": "hello.webhook", "label": "Webhook URL", "type": "string", "default": "" }
]
}
}Manifest fields
| Field | Required | Description |
|---|---|---|
id |
Yes | Reverse-DNS id, e.g. com.author.myplugin |
name |
Yes | Display name (max 120 chars) |
version |
Yes | Semver, e.g. 1.0.0 |
publisher |
Yes | Publisher slug |
description |
No | Short description for marketplace |
minIdeVersion |
No | Minimum Boongle IDE version |
main |
Yes | Entry script filename (.bplugin or .js) |
contributes |
No | Declarative contributions (see below) |
Boongle Plugin Script (main.bplugin)
A JavaScript module executed in the IDE sandbox. Export activate and optional deactivate:
// main.bplugin — Boongle Plugin Script
module.exports = {
activate(boongle) {
// Commands
boongle.commands.register('hello.say', () => {
boongle.ui.notify('Hello from your plugin!', 'info');
});
// Sidebar panel (HTML content)
boongle.sidebar.register('hello.panel', {
title: 'Hello',
render(container) {
container.innerHTML = '<p style="padding:12px;color:#ccc">Hello World</p>';
},
});
// Agent tool — available to the AI when plugin is installed
boongle.agent.registerTool('hello_greet', {
description: 'Greet someone by name',
parameters: {
type: 'object',
properties: { name: { type: 'string' } },
required: ['name'],
},
async execute({ name }) {
return `Hello, ${name}! — from Hello World plugin`;
},
});
// External integration hook
boongle.integrations.register('slack', {
label: 'Slack',
async connect(config) {
boongle.ui.notify('Slack connected (demo)', 'info');
return { ok: true };
},
});
// Settings change listener
boongle.settings.onChange((key, value) => {
if (key === 'hello.webhook') {
console.log('[hello] webhook updated', value);
}
});
// Play a bundled sound from sounds/notification.mp3
boongle.commands.register('hello.chime', async () => {
await boongle.audio.play('sounds/notification.mp3', { volume: 0.8 });
boongle.ui.notify('Chime played!', 'info');
});
// Listen for workspace changes
boongle.events.on('workspace-changed', (detail) => {
console.log('Workspace:', detail?.rootPath);
});
},
deactivate() {
// Cleanup (optional)
},
};boongle API reference
boongle.commands
| Method | Description |
|---|---|
register(id, handler) |
Register a command. id must match contributes.commands[].id |
execute(id, ...args) |
Run a registered command |
boongle.ui
| Method | Description |
|---|---|
notify(message, type?) |
Toast notification. type: info | warning | error | promo |
showPanel(id) |
Focus a sidebar panel |
confirm(message, title?) |
Native confirm dialog — returns boolean |
prompt(message, defaultValue?) |
Native prompt — returns string or null |
boongle.assets
Read files bundled inside your .bplugin package (images, sounds, JSON, etc.).
| Method | Description |
|---|---|
exists(path) |
Check if a relative asset path exists |
readText(path) |
Read a text file from the package |
readDataUrl(path) |
Read any file as a data: URL (great for or Audio) |
list(subdir?) |
List all asset paths in the package |
Supported audio formats for boongle.audio: .mp3, .wav, .ogg, .m4a, .aac, .webm, .flac.
boongle.audio
| Method | Description |
|---|---|
play(path, { volume?, loop?, id? }) |
Play a sound from the package. Returns { id, stop } or null |
stop(id?) |
Stop one sound by id, or stop all plugin sounds if no id |
// Play once at 80% volume
await boongle.audio.play('sounds/success.mp3', { volume: 0.8 });
// Looping ambient sound with manual stop
const ambient = await boongle.audio.play('sounds/ambient.ogg', {
loop: true,
id: 'ambient',
volume: 0.3,
});
// later: ambient?.stop();
// or: boongle.audio.stop('ambient');Note: Browsers may block autoplay until the user interacts with the IDE (clicks a button, runs a command, etc.). Trigger sounds from command handlers or UI clicks for best results.
boongle.shell
| Method | Description |
|---|---|
openExternal(url) |
Open a URL in the system default browser |
boongle.clipboard
| Method | Description |
|---|---|
writeText(text) |
Copy text to clipboard |
readText() |
Read text from clipboard |
boongle.net
| Method | Description |
|---|---|
fetch(url, { method?, headers?, body? }) |
HTTP request proxied through the IDE (max 5 MB response) |
Returns { ok, status, body, error? }.
boongle.events
| Method | Description |
|---|---|
on(event, handler) |
Subscribe to IDE events. Returns unsubscribe function |
| Event | Detail |
|---|---|
workspace-changed |
{ rootPath } — workspace folder opened/closed |
plugins-changed |
{ id, installed } — plugin installed/uninstalled |
agent-turn-finished |
{ reason, chatId?, agentMode? } — AI agent turn ended. reason is completed (natural finish) or stopped (user cancelled) |
// Play a sound when the agent finishes (not when the user hits Stop)
boongle.events.on('agent-turn-finished', (detail) => {
if (detail?.reason !== 'completed') return;
void boongle.audio.play('sounds/chime.mp3');
});boongle.timers
| Method | Description |
|---|---|
setTimeout(fn, ms) |
Like window.setTimeout — auto-cleared on plugin deactivate |
setInterval(fn, ms) |
Like window.setInterval — auto-cleared on plugin deactivate |
clearTimeout(id) |
Clear a timeout |
clearInterval(id) |
Clear an interval |
boongle.sidebar
Register a sidebar panel. Panels declared in bplugin.json under contributes.sidebarPanels automatically get an activity bar icon in the IDE.
| Method | Description |
|---|---|
register(id, { title, render }) |
Register a sidebar panel. render(container) receives a DOM element |
Manifest example (adds activity bar icon):
"contributes": {
"sidebarPanels": [
{ "id": "hello.panel", "title": "Hello", "icon": "comment" }
]
}icon is a Codicon name without the codicon- prefix (e.g. "bell", "extensions").
Call boongle.ui.showPanel('hello.panel') to focus the panel programmatically.
boongle.settings
Read/write plugin settings. Declare defaults in bplugin.json under contributes.settings — they appear in Boongle IDE Settings → Plugins and persist locally.
| Method | Description |
|---|---|
get(id) |
Read a plugin setting (falls back to manifest default) |
set(id, value) |
Write a plugin setting (persisted locally) |
onChange(callback) |
Listen for setting changes |
Manifest example:
"contributes": {
"settings": [
{ "id": "hello.enabled", "label": "Enable feature", "type": "boolean", "default": true },
{ "id": "hello.webhook", "label": "Webhook URL", "type": "string", "default": "" },
{ "id": "hello.volume", "label": "Volume", "type": "number", "default": 80 }
]
}Supported type values: boolean, string, number.
For rich UI (file pickers, custom layouts), also register a boongle.sidebar panel — the Agent Done Sound plugin uses both.
boongle.agent
| Method | Description |
|---|---|
registerTool(name, { description, parameters, execute }) |
Register an AI agent tool |
unregisterTool(name) |
Remove tool on deactivate |
Agent tools are merged into the main agent loop when your plugin is installed. The agent can call them like built-in tools.
boongle.integrations
| Method | Description |
|---|---|
register(id, { label, connect, disconnect? }) |
Register an external app integration |
Use for Slack, Discord, Jira, custom webhooks, etc.
boongle.storage
| Method | Description |
|---|---|
get(key) |
Read plugin-local persistent value |
set(key, value) |
Write plugin-local persistent value |
remove(key) |
Delete a stored value |
Plugin settings (boongle.settings) persist in local storage per plugin. boongle.storage is separate in-memory key/value data for the session.
boongle.workspace
| Property / Method | Description |
|---|---|
rootPath |
Current workspace folder path (or null) |
readFile(relativePath) |
Read a file from workspace (async via IPC) |
onDidChangeRoot(callback) |
Fired when workspace folder changes |
Building a .bplugin package
- Create a folder with
bplugin.jsonandmain.bplugin - Zip the folder contents (not the parent folder):
cd my-plugin
zip -r ../my-plugin.bplugin bplugin.json main.bplugin README.md icon.pngOn Windows (PowerShell):
Compress-Archive -Path bplugin.json, main.bplugin, README.md -DestinationPath my-plugin.bpluginNote:
.bpluginis a zip file. Rename.zip→.bpluginif your zip tool does not support custom extensions.
Submitting for approval
- Go to boongle-ide.bond/plugins/submit
- Sign in with your existing Boongle account email and password
- Drop your
.bpluginfile — the page readsbplugin.jsonand detects new vs update - For updates: bump
versioninbplugin.json, add a changelog, then submit - Wait for admin review
New vs update
| New plugin | Update | |
|---|---|---|
| Plugin id | Not in marketplace yet | Same id already published |
| Version | Any valid semver | Must be higher than published |
| Changelog | Optional | Required |
| Author | Your signed-in email | Must match original publisher email |
You can put changelog or releaseNotes in bplugin.json — the submit form auto-fills from it.
Submit API
POST /api/plugins/submit
Authorization: Bearer <supabase-access-token>
Content-Type: application/json
{
"authorEmail": "[email protected]",
"repositoryUrl": "https://github.com/you/my-plugin",
"changelog": "Fixed sound on Windows",
"manifest": { ...bplugin.json contents... },
"packageBase64": "<base64-encoded .bplugin zip>"
}Response: { "ok": true, "id": "
Lookup published plugin (for update UI)
GET /api/plugins/lookup?pluginId=com.example.helloResponse when published: { "exists": true, "pluginId": "...", "name": "...", "version": "1.0.0", ... }
Marketplace catalog API
Used by Boongle IDE to list installable plugins.
GET /api/plugins/catalogResponse:
{
"plugins": [
{
"pluginId": "com.example.hello",
"name": "Hello World",
"version": "1.0.0",
"publisher": "example",
"description": "A demo plugin",
"downloadUrl": "/api/plugins/download/com.example.hello",
"contributes": { ... },
"installCount": 42
}
]
}Download published plugin
GET /api/plugins/download/:pluginIdReturns the .bplugin zip binary.
IDE install flow
- IDE fetches
GET /api/plugins/catalogon startup (after auth) - User clicks Install in Plugins marketplace
- IDE downloads
.bpluginviadownloadUrl - Package is extracted to
%AppData%/Boongle IDE/bplugins// main.bpluginis activated; contributions register immediately- Activity bar —
contributes.sidebarPanelsadds icons; click to open the panel - Boongle IDE Settings → Plugins —
contributes.settingsrenders boolean/string/number controls - Uninstall removes the folder and deactivates the plugin
Built-in plugins
Some plugins ship with Boongle IDE (e.g. GitHub). They use the same install state (plugins.json) but are not downloaded from the marketplace.
Admin review
Submissions are reviewed at /plugins/admin (admin login required).
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/plugins/admin/submissions |
GET | Bearer token | List submissions (?status=pending) |
/api/plugins/admin/download/:id |
GET | Bearer token | Download submission .bplugin |
/api/plugins/admin/approve |
POST | Bearer token | Approve → publishes to marketplace |
/api/plugins/admin/reject |
POST | Bearer token | Reject submission |
Approve body:
{
"submissionId": "<uuid>",
"reviewerNotes": "Looks good",
"categories": ["productivity", "agent"]
}Versioning & updates
- Plugin
idis stable across versions - Drop a package with the same
idand a higher semver to submit an update (changelog required) - Only the original author email can submit updates for a published plugin
- Submitting a new version replaces the marketplace entry on approval
- IDE checks installed version vs catalog version and shows Update when newer is available
Security
- Plugin scripts run in a sandboxed renderer context with limited
boongleAPI - No raw
require('fs')or Node APIs in plugin scripts - File/workspace access goes through
boongle.workspaceIPC guards - Admin must approve all marketplace listings before they appear in the IDE
Example: plugin with custom sound
bplugin.json
{
"id": "com.demo.chime",
"name": "Chime",
"version": "1.0.0",
"publisher": "demo",
"description": "Plays a chime sound on command",
"main": "main.bplugin",
"contributes": {
"commands": [{ "id": "chime.play", "title": "Play Chime" }]
}
}main.bplugin
module.exports = {
activate(boongle) {
boongle.commands.register('chime.play', async () => {
const played = await boongle.audio.play('sounds/chime.mp3', { volume: 0.9 });
if (!played) {
boongle.ui.notify('Could not play chime — add sounds/chime.mp3 to your package.', 'warning');
}
});
},
};Package must include sounds/chime.mp3 in the zip.
Example: minimal plugin
bplugin.json
{
"id": "com.demo.ping",
"name": "Ping",
"version": "1.0.0",
"publisher": "demo",
"description": "Adds a ping agent tool",
"main": "main.bplugin",
"contributes": {
"agentTools": [
{ "name": "ping", "description": "Reply pong" }
]
}
}main.bplugin
module.exports = {
activate(boongle) {
boongle.agent.registerTool('ping', {
description: 'Reply pong',
parameters: { type: 'object', properties: {} },
async execute() {
return 'pong';
},
});
},
};Questions? Open an issue or contact [email protected].