Choose a kind of integration
| Kind | What it is for |
|---|---|
| Executable (fire and forget) | Starts another app without waiting for it to finish or collecting its output |
| Standard input/output filter | Passes text to a program and takes the converted result back |
| REST API (HTTP POST) | Sends JSON and takes the response body back |
| MCP client | Calls a tool on an MCP server and takes the reply text back |
Register a tool and run it
- Choose Settings → External Tools → + Add Tool.
- Enter a name, choose the tool type, and fill in the fields for that type, such as an executable path or endpoint URL.
- If the tool accepts text, choose the input to send. If it returns a result, choose how the output should be handled.
- Set Require an open file and Require selected text as needed.
- Save the settings and run
/<tool name>in the terminal.
You can also run tools from the plug icon on the formatting toolbar. Each registered tool appears on the Shortcuts and Gestures settings tabs, where you can assign a shortcut or gesture to it.
Pass the current document to a tool
Use the placeholders below in arguments and elsewhere.
| Placeholder | What it holds |
|---|---|
{file} / {dir} | The file path, and the folder containing it |
{selection} | The selected text |
{workspace} | The root of the workspace |
{input} | What you typed after the tool name in the terminal |
{full_document} | The whole document. Available in a REST body and in MCP arguments JSON |
{token} | The registered token. Available in REST headers and body, and in MCP arguments JSON |
In JSON, use placeholders ending in _json. These escape quotation marks and line breaks and include the surrounding quotes, so the result is a valid JSON string. Do not add another pair of quotes around the placeholder.
{"text": {selection_json}, "instruction": {input_json}}What to check per kind
- Standard input/output filter: choose what goes in, such as the selection, the whole document or the terminal argument. Check the path to the executable and its working folder.
- REST API: an external endpoint has to be HTTPS. The response body is taken as it is, so a single field cannot be extracted out of JSON. Tokens are registered with Set Token….
- MCP: for standard input/output, give the command, its arguments and its environment variables; for HTTP, give the endpoint. Then set the tool name and the arguments JSON. To use
npxoruvx, install the runtime they need separately.
Choose where the result goes
The result can replace the selection, be inserted at the cursor, replace the whole document, go to the clipboard, become a new file, or be shown in the terminal. Replacing the whole document is not saved automatically; check the result before saving.
Switching tabs after a run has started does not move its output: it is applied to the tab the run started in. If that tab has been closed, the output is opened in a new tab. A run in progress can be cancelled from the progress window or from the terminal.
Move your definitions to another machine
Use Export to JSON… / Import from JSON… on the External Tools tab. Check the executable paths and URLs before importing. Token values are not written out, so register them again on the other machine.
External tools cannot be run while the license does not allow editing. Check the state under Licensing and activation.