Skip to content

Create a custom tool

DuckTapeKiller edited this page Sep 13, 2026 · 1 revision

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.

Add a custom tool

  1. Switch to the mode that should have the tool.

  2. Open Settings > TOOLS and find MANAGE CUSTOM TOOLS.

  3. 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_until
    Description 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
  4. Press SAVE.

The tool appears in the list with its type and description. To remove it, press × and confirm.

Describe the inputs

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).

JavaScript tools

Your code runs as the body of an async function in a separate worker thread:

  • args holds the object of inputs the model sent.
  • return a 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 require Node.js built-in modules, so it isn't a security sandbox. Only use code you trust.
  • JavaScript tools don't ask for permission.

Shell tools

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: and ERROR: sections, or "Command executed successfully with no output."

Placeholders are quoted the way macOS and Linux shells expect.

Limits of custom tools

  • 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.

Troubleshooting

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

For developers

  • Custom tools are saved per mode in ~/dive/custom_skills-<mode>.json, as an array of objects with name, description, type (shell or javascript) and code. POST /api/custom-skills in routes/skills.js checks that each field is a string.
  • getLocalNativeTools() and getCloudSkillsPolicyPrompt() in routes/chat.js offer them with an empty parameter schema.
  • They run from the last branch of executeSkill() in skills.js: placeholders are substituted and the command goes to executeShellCommand() in skills/code.js, or the code goes to runCustomJsSkill().

Read next

Clone this wiki locally