Repository navigation
Create a tool
DuckTapeKiller edited this page Sep 13, 2026
·
1 revision
A tool lets the model do something: look something up, run a program, change a file. Dive has three ways to add one, and Pi mode has a fourth. This page helps you choose.
If what you want is a way of working, such as a checklist, a house style or a procedure, you don't need a tool. Write a skill instead.
| Custom tool | External tool | MCP server | pi extension | |
|---|---|---|---|---|
| What it is | A shell command or a JavaScript snippet typed into Settings | A Node.js module in ~/dive/plugins
|
A separate program that speaks the Model Context Protocol | An extension for pi |
| Where you set it up | Settings > TOOLS > MANAGE CUSTOM TOOLS | A folder or .js file in ~/dive/plugins
|
Settings > TOOLS > MCP SERVERS |
~/.pi/agent/extensions or a pi package |
| Modes | Only the mode you create it in | llama.cpp, LM Studio, Ollama and Cloud, with a switch in each | llama.cpp, LM Studio and Ollama; the section isn't shown in Cloud | Pi |
| Inputs the model is shown | None: the model only has your description | The JSON Schema you write | The server's own schema | The schema you give pi |
| Asks for permission | Shell: every time. JavaScript: never | Only if it sets requiresConfirmation
|
Never | Up to the extension |
| Time limit | Shell: 5 seconds. JavaScript: 10 seconds | 60 seconds by default, from 1 second to 60 minutes | Dive sets none | Up to pi |
| Slash command | No | Yes | No | Yes, as a pi command |
| Usable in other apps | No | No | Yes, in any MCP client | No |
| What it can reach | Shell: anything, once you allow it. JavaScript: Node.js built-in modules | Everything, because it runs inside Dive's server | Whatever the program does | Everything pi can reach |
- A custom tool is the quickest: wrap a command-line program, or a few lines of JavaScript, for one mode. The model isn't shown any declared inputs, so describe the inputs in the tool's description and keep them simple. See Create a custom tool.
- An external tool is a proper tool: typed inputs, a slash command, an optional permission prompt, a longer time limit, and a switch in every mode. You write it in JavaScript for Node.js. See Create an external tool.
- An MCP server makes sense when the tool you want already exists as one, or when you want the same tool in Claude Code and other MCP clients. See Connect an MCP server.
-
A pi extension is the only way to add a tool to Pi mode, because Dive's own tools don't reach pi. pi's extension documentation covers
pi.registerTool(), and Pi mode explains where pi loads extensions from.
Dive looks for a native tool first, then an external tool, then a custom tool, and runs the first it finds. MCP tools can't clash with these, because their names always start with mcp__.
- Native tools, to check whether Dive already has what you need
- Safety
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