# Your own tools Source: https://docs.ideharmony.com/customization/user-tools > [!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_`. 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/.json` in a project | Tools that belong to that repository | | `tools/.json` in your Harmony home | Your own tools, in every project | A project tool replaces a global tool of the same name. ```json { "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_`. | | `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: ```bash 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.