Your own tools
Describe a script in a small JSON file and every agent in Harmony can call it as a tool, whichever provider it runs.
NOTE
Your own tools are not in 3.25.8, the current release. They arrive with the next release. This page describes them so you can prepare.
Write a small JSON file that names a script and its arguments, and every agent
in Harmony gets it as a tool called user_<name>. That includes Claude Code,
Codex, the Harmony Agent and any other MCP client, with no per-agent setup.
New and edited tools appear within a few seconds, without restarting the
agents.
Add a tool
The quickest start is Settings → Tools → Your tools → Add an example tool.
It writes a working example_echo tool to your global tools folder, never
over a file you already have, and opens the folder. Copy the pair to make
your own.
Or write one JSON file per tool:
| Folder | For |
|---|---|
.harmony/tools/<name>.json in a project | Tools that belong to that repository |
tools/<name>.json in your Harmony home | Your own tools, in every project |
A project tool replaces a global tool of the same name.
{
"name": "preview_url",
"description": "Print the preview URL for a branch.",
"command": ["node", "scripts/preview-url.mjs"],
"args": {
"branch": { "type": "string", "description": "Git branch", "required": true }
},
"timeoutSeconds": 30
}
| Field | Rule |
|---|---|
name | 2 to 48 characters: lowercase letters, digits and _. The agent sees user_<name>. |
description | What it does and when to use it. The agent reads this to decide. |
command | An argument list, run without a shell, so an argument can never be read as shell syntax. On Windows, run a .cmd file as ["cmd", "/c", "x.cmd"]. |
args | Optional. Each argument has a type (string, number or boolean), a description and required. |
timeoutSeconds | Optional. Default 60, at most 300. The program and anything it started are stopped when time runs out. |
approval | Optional. "never" (the default) or "always". See below. |
What the program gets
- Working directory: the agent's.
- Arguments: JSON on standard input, and the same JSON in
HARMONY_TOOL_ARGS. HARMONY_TOOL_NAME: the tool's name.
Whatever it prints is the result. A non-zero exit, a timeout, or a program that cannot start comes back to the agent as an error that says which, with its error output. Each stream is capped at 64 KB. If the agent goes away mid-call, the tool is stopped with it.
A project's tools need your trust
Your global tools always load. A project's .harmony/tools/ comes with the
repository, so a cloned repo could otherwise hand your agents tools with
reassuring names. They load only after you choose Trust this project's
tools in Settings → Tools → Your tools, with that project in the active
pane. Stop trusting turns them off again. Running agents pick up either
change within a few seconds. Until then, agents are told the project has
tools you have not trusted.
SECURITY
Trusting a project's tools lets every agent in it run those programs as you. Read them first, as you would read any script from that repository.
Ask before every run
Add "approval": "always" to a tool and Harmony asks you before every run,
whichever agent calls it and whatever that agent's own permission mode is.
The dialog names the agent, the program, the folder and the arguments, and
Deny is the default. If you deny it, close the dialog, don't answer
within 2 minutes, or Harmony isn't running, the tool doesn't run.
From the command line
The same tools work without MCP:
harmony user-tool list
harmony user-tool run example_echo --args-json '{"message":"hi"}'
They run in the current folder, follow project trust and the Settings switch,
and need no background service. (harmony tool is something else: the
service's capability registry.)
Turning it off
Settings → Tools → Run user tools. It is checked on every call, so it takes effect for running agents. An agent app that asks before running any tool still asks.