Repository navigation
Create an external tool
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.
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.
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.
Ask the model how many words a paragraph has, or type the command:
/wordcount The quick brown fox jumps over the lazy dog.
| 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.
| 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 |
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.
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:
- the tool's only required text input, if it has exactly one;
- otherwise its first text input, in the order you declared them;
- 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.
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.
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.
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 |
With the propose_plugin tool switched on (it starts off), you can ask the model to write a plugin for you:
- 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. - The draft is saved in
~/dive/plugin-drafts/<name>/asplugin.jsonandindex.js. Nothing loads from that folder. - Settings > TOOLS shows it under DRAFTS AWAITING YOUR APPROVAL, with the full code.
- 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.
- The loader is
plugins.js:loadPlugins(),validateSkill(),getPluginSkillSnapshot(),executePluginSkill().PLUGIN_CONTEXT_KEYSis the allowlist of context fields a plugin receives. - Each request works from a snapshot.
createSkillContext()inroutes/chat.jskeeps 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()inslash_commands.js. Drafts are written byexecuteProposePlugin()inskills/meta.js. - Endpoints:
GET /api/plugins,POST /api/plugins/reload,GET /api/plugins/drafts,POST /api/plugins/drafts/approveandPOST /api/plugins/drafts/delete.
These pages describe Dive 5.0.8. Source code: DuckTapeKiller/dive. Spotted a mistake? Open an issue.
Get started
Tools and skills
Build your own
Share and stay safe
How Dive works
Help