create-donobu-plugin

create-donobu-plugin is the official scaffolding CLI for Donobu Studio plugins. It generates a TypeScript workspace wired to Donobu’s plugin API, pins dependencies to whatever versions your local Studio installation already uses, and ships with helper utilities so you can focus on describing new tools instead of wiring.

How Donobu loads plugins

• Donobu watches a plugins directory inside its working data folder (macOS: ~/Library/Application Support/Donobu Studio/plugins, Windows: %APPDATA%/Donobu Studio/plugins, Linux: ~/.config/Donobu Studio/plugins).
• Each plugin ships a bundled dist/index.mjs that exports one async function named loadCustomTools(dependencies). When Donobu starts it imports every plugin bundle and calls that function to collect tools.
• npm exec install-donobu-plugin builds your project and copies the resulting dist/ folder into <workingDir>/plugins/<plugin-name>, so restarting Donobu is enough to pick up changes.

Keep those three rules in mind and your plugin will load reliably.

Prerequisites

• Node.js 18+ and npm 8+
• A local Donobu Studio installation (desktop or backend) so the installer has somewhere to copy the plugin bundle
• Playwright browsers installed (Donobu will prompt you if they are missing)
• Write access to the Donobu Studio working directory

Installation

npx create-donobu-plugin my-support-tools

Provide the plugin name as the first argument. Names may include lowercase letters, numbers, hyphens, and underscores. The CLI prints usage information if the argument is missing or invalid.

Quick start

1. Scaffold a plugin: npx create-donobu-plugin my-support-tools
2. cd my-support-tools && npm install
3. Implement your tools in src/index.ts
4. npm run build
5. npm exec install-donobu-plugin
6. Restart Donobu Studio and verify the tools appear in the UI/logs

Generated project layout

| Item | Description | | -------------------- | ------------------------------------------------------------------------------------------------------ | | package.json | Private ESM package whose main/types fields point to dist/. | | tsconfig.json | NodeNext compiler settings that emit JS + declarations into dist/. | | esbuild.config.mjs | Bundles the compiled JS into dist/index.mjs, keeping Donobu and Playwright as external dependencies. | | src/index.ts | Entry point that must export loadCustomTools(dependencies) and return an array of tools. | | README.md | Template instructions for the team that owns the generated plugin. |

Because the scaffold reuses the Donobu versions already on disk, regenerating the project after a Donobu upgrade is the fastest way to stay in lockstep.

Authoring tools

Every plugin's index.ts exports loadCustomTools(dependencies) and returns an array of Tool instances.

// Note that non-type imports from 'donobu' should be extracted from the given
// 'deps.donobu' parameter in 'loadCustomTools'.
import type { Tool, PluginDependencies } from 'donobu';
import { z } from 'zod/v4';

export async function loadCustomTools(
  deps: PluginDependencies
): Promise<Tool<any, any>[]> {
  // Register your custom tools here.
  return [
    // Here is a small example tool for reference.
    deps.donobu.createTool(deps, {
      // The tool name, description, and schema are shared with the Donobu agent
      // to help it decide when, where, and how this tool will be called.
      name: 'judgeWebpageTitle',
      description: 'Judge the quality of a title to a webpage.',
      schema: z.object({ webpageTitle: z.string() }),
      // This example tool uses a GPT/LLM so we call it out here.
      requiresGpt: true,
      call: async (context, parameters) => {
        // 'requiredGpt' is true, so we are guaranteed a valid gptClient handle.
        const resp = await context.gptClient!.getMessage([
          {
            type: 'user',
            items: [
              {
                type: 'text',
                text: `Judge the quality of this webpage title on a scale of 1 (worst) to 10 (best) and explain why.
                       Title: ${parameters.webpageTitle}`,
              },
            ],
          },
        ]);
        return {
          // Returning false or throwing an exception will signal tool call failure.
          isSuccessful: true,
          // This is what is shared back with the Donobu agent.
          forLlm: resp.text,
          // Metadata is persisted with the tool call result, but is not shared
          // with the Donobu agent, so this can be used to store large complex data.
          metadata: null,
        };
      },
    }),
  ];
}

Working with injected dependencies

• deps.donobu exposes the public SDK: the base Tool class, PlaywrightUtils, logging helpers, type definitions, etc.
• deps.playwright points to the same Playwright build Donobu uses, so your plugin and the core runtime stay aligned.
• Feel free to add your own dependencies; esbuild bundles everything except the packages listed in external.

Build and install

npm run build
npm exec install-donobu-plugin

npm run build cleans dist/, reinstalls dependencies (to ensure version parity), runs TypeScript, and bundles the result. npm exec install-donobu-plugin validates the current folder, infers the plugin name (prefers package.json, falls back to the git repo name or $USER), and copies dist/ into the Donobu plugins directory. Restart Donobu after installing so the new bundle is loaded.

Recommended development loop

1. Make changes in src/
2. npm run build && npm exec install-donobu-plugin
3. Restart Donobu Studio or the backend process
4. Trigger your tool from the UI or API to verify behavior

Because the default build script runs npm install, consider splitting the script into build and bundle variants if you need faster inner-loop iterations.

Troubleshooting

• Plugin not appearing: Ensure npm exec install-donobu-plugin ran successfully and that dist/index.mjs exists. Restart Donobu and watch the logs for plugin loading messages.
• Schema errors: Zod throws runtime errors when inputs don’t match your schema. Log the error message to quickly see which field failed.
• Version mismatch: If Donobu upgrades Playwright or its SDK, re-run the scaffold (or update the plugin’s dev dependencies) so you stay compatible.