Repository navigation
Create a custom tool
A custom tool is the quickest way to give the model a new ability: a shell command or a few lines of JavaScript, typed straight into Settings. It belongs to the mode you create it in, and it works in llama.cpp, LM Studio, Ollama and Cloud mode.
-
Switch to the mode that should have the tool.
-
Open Settings > TOOLS and find MANAGE CUSTOM TOOLS.
-
Press ADD NEW TOOL and fill in every field:
Field What to enter Tool Name The name the model calls. Stick to letters, digits and underscores, for example days_untilDescription What the tool does, when to use it, and the inputs it expects Type Shell Command or Javascript (Node) Code or Shell Command The command or the code -
Press SAVE.
The tool appears in the list with its type and description. To remove it, press × and confirm.
Dive offers a custom tool to the model with no declared inputs, so the model learns what to send from the description alone. Always name the inputs there:
Counts the days from today until a date. Input: date (the date as YYYY-MM-DD).
Your code runs as the body of an async function in a separate worker thread:
-
argsholds the object of inputs the model sent. -
returna value to send it back to the model. Objects are sent as JSON. - You can use
await.
Example, with Type set to Javascript (Node) and the description above:
const target = new Date(String(args.date || ""));
if (Number.isNaN(target.getTime())) return "Give the date as YYYY-MM-DD.";
const days = Math.ceil((target.getTime() - Date.now()) / 86400000);
return `${days} days until ${args.date}`;Limits worth knowing:
- The code has 10 seconds, after which it's stopped.
- The worker's memory is capped, at 64 MB for long-lived objects.
- The worker can
requireNode.js built-in modules, so it isn't a security sandbox. Only use code you trust. - JavaScript tools don't ask for permission.
Your command can contain placeholders in double braces, one for each input. Dive replaces each placeholder with the value the model sent, wrapped in single quotes and escaped, so a value can't break out of the command. A placeholder the model didn't send stays as you typed it.
Example, with Type set to Shell Command:
-
Description:
Shows how much disk space a folder uses. Input: path (an absolute folder path). -
Command:
du -sh {{path}}
Because the value arrives in single quotes, the shell doesn't expand ~ inside it. That is why the description asks for an absolute path.
How shell tools run:
- They ask for your permission every time, like
shell_command. - They run in your home folder, with a 5-second limit.
- The model receives the output in
STDOUT:,STDERR:andERROR:sections, or "Command executed successfully with no output."
Placeholders are quoted the way macOS and Linux shells expect.
- No on/off switch. Delete a tool to remove it.
- No slash command.
- Only one mode. Create the tool again in each mode that should have it.
- If an external tool has the same name, the external tool runs instead.
For typed inputs, a slash command or a longer time limit, write an external tool.
| Symptom | What to do |
|---|---|
| The model calls the tool with the wrong inputs | Name the inputs, and their format, in the description |
Custom Tool Error (name): Custom JavaScript tool timed out after 10000ms |
Make the code faster, or turn it into an external tool with a longer timeoutMs
|
Custom Tool Error (name): ... with another message |
The code threw an error, or the worker couldn't start. The message after the colon says which |
A shell command runs with {{name}} left in it |
The model didn't send that input. Check the placeholder's spelling against the description |
| "All fields are required." | Fill in the name, the description and the code |
- Custom tools are saved per mode in
~/dive/custom_skills-<mode>.json, as an array of objects withname,description,type(shellorjavascript) andcode.POST /api/custom-skillsinroutes/skills.jschecks that each field is a string. -
getLocalNativeTools()andgetCloudSkillsPolicyPrompt()inroutes/chat.jsoffer them with an empty parameter schema. - They run from the last branch of
executeSkill()inskills.js: placeholders are substituted and the command goes toexecuteShellCommand()inskills/code.js, or the code goes torunCustomJsSkill().
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