Skip to content

Create an external tool

DuckTapeKiller edited this page Sep 13, 2026 · 1 revision

An external tool is a plugin: a Node.js module in ~/dive/plugins that adds one or more tools, and optionally slash commands, without changing Dive itself. External tools work in llama.cpp, LM Studio, Ollama and Cloud mode, with a switch in each.

A plugin runs inside Dive's server with full access to your computer. Only install code you trust.

1. Create the plugin

Make a folder with two files:

~/dive/plugins/word-count/
├── plugin.json
└── index.js

plugin.json:

{
  "name": "word-count",
  "description": "Counts words, sentences and characters.",
  "version": "1.0.0"
}

index.js:

module.exports = {
  skills: [
    {
      name: "word_count",
      description:
        "Counts the words, sentences and characters in a text. Use when the user asks how long a text is.",
      parameters: {
        type: "object",
        properties: {
          text: { type: "string", description: "The text to count" },
        },
        required: ["text"],
      },
      async execute(args) {
        const text = String(args.text || "");
        const words = text.trim().split(/\s+/).filter(Boolean).length;
        const sentences = (text.match(/[.!?]+(\s|$)/g) || []).length;
        return `${words} words, ${sentences} sentences, ${text.length} characters`;
      },
    },
  ],
  commands: { wordcount: "word_count" },
};

The list is called skills for historical reasons; it holds the plugin's tools.

2. Load it

Open Settings > TOOLS and press RELOAD EXTERNAL TOOLS. Under EXTERNAL TOOLS, the plugin appears with its version, its description, its command /wordcount, and a switch for word_count. Tools start switched on.

3. Try it

Ask the model how many words a paragraph has, or type the command:

/wordcount The quick brown fox jumps over the lazy dog.

What a plugin exports

Field Required What it's for
skills Yes An array of tools. A plugin with no tools fails to load
commands No Slash commands, mapping a command name to one of this plugin's tools
name, description, version No Shown in Settings. They override plugin.json, which overrides the folder's name

A plugin can also be a single .js file directly in ~/dive/plugins, exporting the same object. Files and folders whose names start with a dot are skipped.

Each tool

Field Required What it does
name Yes The name the model calls. It starts with a letter and uses letters, digits and underscores. It must be unique across all plugins
description Yes What the tool does and when to use it. The model chooses tools by their descriptions
parameters No A JSON Schema for the inputs. Without one, the tool takes no inputs
execute(args, context) Yes The function Dive runs, with or without async
requiresConfirmation No true makes Dive ask for your permission before every run
timeoutMs No How long execute may take: 60,000 by default, from 1,000 to 3,600,000

What execute receives and returns

args is the object of inputs the model sent. context has three fields:

Field Value
dataDir Dive's data folder, ~/dive by default
mode The mode the request came from, for example llamacpp
allowShellCommand true when the tool asked for permission and you allowed it

Return a string and the model receives it as it is. Any other value is sent as JSON, and undefined or null as an empty string. If execute throws, or runs past its time limit, the model receives Plugin Tool Error (word_count, from plugin "word-count"): ... with the reason, and Dive carries on.

Slash commands

commands maps a command name to one of the plugin's own tools. The name is lowercased and may use letters, digits, underscores and hyphens, starting with a letter. The first plugin to claim a command keeps it, and a native command with the same name always wins.

When you type the command, the text after it goes to one input:

  1. the tool's only required text input, if it has exactly one;
  2. otherwise its first text input, in the order you declared them;
  3. otherwise an input called input.

With nothing typed, the tool gets no inputs, unless the chosen input is required, in which case Dive refuses with "/wordcount requires text." A command only works in modes where its tool is switched on.

Asking for permission

Set requiresConfirmation: true on any tool that downloads things, writes files or runs programs. Dive then opens a permission dialog before each run, titled "Action Request" followed by the tool's name and showing the inputs. The request and your answer go into ~/dive/security-events.jsonl. See How the model uses tools.

Dependencies and reloading

Dive loads a plugin with Node's require, so a plugin can keep its own node_modules folder next to index.js.

RELOAD EXTERNAL TOOLS reloads each plugin's index.js. Other files that index.js requires stay cached until Dive's server restarts, so restart it after changing those.

When a plugin fails to load

The error appears under the plugin in Settings, and the rest of Dive keeps working. If one tool in a plugin is invalid, the others still load.

Error Cause
directory plugin has no index.js The folder has no index.js
module.exports is not an object The file doesn't export an object
plugin exports no skills The skills array is missing or empty
invalid tool name "..." (letters, digits, underscores) The name breaks the rule
tool "..." is missing a description Add a description
tool "..." is missing an execute() function Add execute
tool "..." already registered by plugin "..." Another plugin uses the name. Rename one
Any other message JavaScript threw it while loading the file

Drafts written by the model

With the propose_plugin tool switched on (it starts off), you can ask the model to write a plugin for you:

  1. The model sends a name, a description and the code. Dive turns the name into lowercase words with hyphens, checks that the code mentions module.exports, and checks its syntax without running it.
  2. The draft is saved in ~/dive/plugin-drafts/<name>/ as plugin.json and index.js. Nothing loads from that folder.
  3. Settings > TOOLS shows it under DRAFTS AWAITING YOUR APPROVAL, with the full code.
  4. APPROVE AND ENABLE asks you to confirm, then moves it into ~/dive/plugins, where it loads and runs. DELETE throws it away.

Read the code before you approve it: approval is the moment the model's code gets full access to your computer.

For developers

  • The loader is plugins.js: loadPlugins(), validateSkill(), getPluginSkillSnapshot(), executePluginSkill(). PLUGIN_CONTEXT_KEYS is the allowlist of context fields a plugin receives.
  • Each request works from a snapshot. createSkillContext() in routes/chat.js keeps only the plugin tools switched on in the mode, and only their commands, so a tool switched off in a mode can't be called or reached by its command there.
  • The command rules are pluginSlashCommandArguments() in slash_commands.js. Drafts are written by executeProposePlugin() in skills/meta.js.
  • Endpoints: GET /api/plugins, POST /api/plugins/reload, GET /api/plugins/drafts, POST /api/plugins/drafts/approve and POST /api/plugins/drafts/delete.

Read next

Clone this wiki locally