All docs

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 docs

Manifest (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

  1. Create a folder with bplugin.json and main.bplugin
  2. Zip the folder contents (not the parent folder):
cd my-plugin
zip -r ../my-plugin.bplugin bplugin.json main.bplugin README.md icon.png

On Windows (PowerShell):

Compress-Archive -Path bplugin.json, main.bplugin, README.md -DestinationPath my-plugin.bplugin

Note: .bplugin is a zip file. Rename .zip → .bplugin if your zip tool does not support custom extensions.

Submitting for approval

  1. Go to boongle-ide.bond/plugins/submit
  2. Sign in with your existing Boongle account email and password
  3. Drop your .bplugin file — the page reads bplugin.json and detects new vs update
  4. For updates: bump version in bplugin.json, add a changelog, then submit
  5. 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": "", "kind": "new" | "update", "previousVersion": "1.0.0" }

Lookup published plugin (for update UI)

GET /api/plugins/lookup?pluginId=com.example.hello

Response when published: { "exists": true, "pluginId": "...", "name": "...", "version": "1.0.0", ... }

Marketplace catalog API

Used by Boongle IDE to list installable plugins.

GET /api/plugins/catalog

Response:

{
  "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/:pluginId

Returns the .bplugin zip binary.

IDE install flow

  1. IDE fetches GET /api/plugins/catalog on startup (after auth)
  2. User clicks Install in Plugins marketplace
  3. IDE downloads .bplugin via downloadUrl
  4. Package is extracted to %AppData%/Boongle IDE/bplugins//
  5. main.bplugin is activated; contributions register immediately
  6. Activity bar — contributes.sidebarPanels adds icons; click to open the panel
  7. Boongle IDE Settings → Plugins — contributes.settings renders boolean/string/number controls
  8. 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 id is stable across versions
  • Drop a package with the same id and 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 boongle API
  • No raw require('fs') or Node APIs in plugin scripts
  • File/workspace access goes through boongle.workspace IPC 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].