Skip to main content

Your own tools

PreviewAvailable on: WindowsmacOSLinuxShips in the preview channel only. Not a stable release.

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:

FolderFor
.harmony/tools/<name>.json in a projectTools that belong to that repository
tools/<name>.json in your Harmony homeYour 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
}
FieldRule
name2 to 48 characters: lowercase letters, digits and _. The agent sees user_<name>.
descriptionWhat it does and when to use it. The agent reads this to decide.
commandAn 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"].
argsOptional. Each argument has a type (string, number or boolean), a description and required.
timeoutSecondsOptional. Default 60, at most 300. The program and anything it started are stopped when time runs out.
approvalOptional. "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.