Write a tool

A toolA plugin that adds a kind of tile, such as a pull request panel. It runs with your access, so it starts switched off.Glossary → adds a kind of tileOne thing in a frame: an agent, a terminal, the Code tile, a browser or a tool.Glossary →. Write one when you want a panel beside your agents that shows something from your project.

Build a Hivemind tool plugin, a new kind of tile drawn by React code inside the app, and, if I want, publish it on HiveHub.

1. Ask me what the tile should show and do, and its name (lowercase letters, digits and dashes).
2. Start it: `hive plugins new tool <name>`. It takes the owner from the GitHub account `gh` is signed in as. If `gh` is not signed in, ask me for my GitHub login and pass `--owner <login>`. Check the folder has `hivemind-tool.json`, `index.js`, `README.md` and `PROMPT.md`.
3. Read `PROMPT.md` in full: it is the whole contract (manifest, what a tile gets, the `hm-plugin://host/` modules, commands). Write what I asked for under its "What I want". Build only from it; never use `window.hive`.
4. Check it, then install it, again after each change: `hive plugins check <folder>` must say ok (it names the file and line of each problem), then `hive plugins install <folder>`. A tool runs with my access, so new or changed code arrives switched off; the same code stays as it was. Ask me before you switch it on with `hive plugins enable tool:@owner/name`.
5. Open it: `hive ctl open-tool @owner/name`. Look at it with `hive ctl tile look <tile>`: check the picture shows what I asked for and its console has no error.
6. Give it one command in the manifest's "commands", answered with `hm.onCommand`, that reports what the tile shows. Check it with `hive ctl plugin call @owner/name <command>`.
7. Done means: `hive plugins list` shows it on with no problem, it reads well in the light and the dark theme, the manifest has a one-line description, a "category" and only the permissions it uses, and `README.md` says what it does and what it runs.
8. Publish only if I say so. Follow the "Publish a plugin" page (https://hivemind.griiken.com/guide/publish-to-hivehub.md): push the folder to a GitHub repository I name, then `hivehub publish <folder>`. If I must sign in, ask me to open the link and type the code myself.

At the end, tell me the tool's id, the command that installs it (`hive plugins install @owner/name`), and anything you could not check.

REFERENCE https://hivemind.griiken.com/guide/tool-plugins.md

The Browser, Issues and the Code tile are tools that come with the app.

Try oneCopy Anchor Link

1. Install a tool from HiveHub:

   Copy Text

   hive plugins install @dip497/worktrees

   Check: it prints installed @dip497/worktrees and says it is off.

2. Switch it on:

   Copy Text

   hive plugins enable tool:@dip497/worktrees

3. Open its tile:

   Copy Text

   hive ctl plugin open tool:@dip497/worktrees

   Check: a tile opens that lists every git worktree of the project.

Or do it in Settings → Plugins, on the HiveHub tab: pick a tool, install it, and turn it on on its page.

api-explorerThe HTTP endpoints your code declares, and a panel to call one.

log-tailFollows a log file, with errors handed to an agent.

dependency-auditKnown vulnerabilities in your lockfiles.

release-checklistClean tree, tests, changelog: each checked, each fixable by an agent.

Every tool on HiveHub is listed on the HiveHub tab; pick Tools to see only tools.

Write oneCopy Anchor Link

Before you startCopy Anchor Link

• Hivemind is installed and open on a project that is a git repository.
• You know a little JavaScript and React.

hive plugins new tool branch

cd branch && hive plugins install . && hive plugins enable tool:@<your login>/branch

import React, { useEffect, useState } from "hm-plugin://host/react.js";
import { Button } from "hm-plugin://host/sdk.js";

const h = React.createElement;

function Tile({ tile, host }) {
  const [branch, setBranch] = useState("…");
  const refresh = () => host.run("git", ["branch", "--show-current"]).then((r) => setBranch(r.stdout.trim() || "(no branch)"));
  useEffect(() => { void refresh(); }, []);
  return h("div", { style: { padding: 16, display: "grid", gap: 8 } },
    h("h3", { style: { margin: 0 } }, tile.name),
    h("p", null, "Branch: ", h("code", null, branch)),
    h(Button, { size: "sm", variant: "outline", onClick: refresh }, "Refresh"));
}

export default { tiles: { "you-branch": Tile } };

const refresh = () => host.run("git", ["log", "-1", "--format=%D: %s"]).then((r) => setBranch(r.stdout.trim()));

Check it workedCopy Anchor Link

• hive plugins list shows the tool on, with no problem.
• Its tile opens from the frame's Open menu.

If it didn'tCopy Anchor Link

Next: Publish a plugin on HiveHub, or ship it with your widgets and views as one: Packages.

Tool referenceCopy Anchor Link

The manifestCopy Anchor Link

{
  "id": "@acme/prs",
  "name": "Pull requests",
  "version": "1.0.0",
  "apiVersion": 1,
  "description": "One line, shown in Settings.",
  "category": "git",
  "entry": "index.js",
  "permissions": ["workspace:spawn"],
  "settings": [
    { "id": "state", "label": "Show", "type": "choice", "values": ["open", "all"], "default": "open" }
  ],
  "tools": [
    {
      "key": "prs", "label": "Pull requests", "description": "What its tile shows.",
      "tileKind": "acme-prs", "size": { "width": 1100, "height": 760 },
      "needsRepo": true, "singleton": true, "glyph": "⇅", "icon": "icon.svg"
    }
  ]
}

What a tile getsCopy Anchor Link

A tile imports the app's own React and parts from hm-plugin://host/: react.js, react-jsx-runtime.js, sdk.js and ui.js. It bundles none of them.

sdk.js has Button, PatchView (a diff), Markdown, Loading, Frame (a page from a server on this machine) and useTileState(hm, key, initial), which keeps a value with the tile across restarts. ui.js is the app's whole UI kit (Button, Input, Dialog…, DropdownMenu…, Switch, toast, …). The built-in Issues tile (apps/desktop/tools/issues in the repository) is the fullest example of how a tile is built. Its colours are not one to copy: it also paints with app variables outside the 11 below, which may change.

Reach the app only through these, never window.hive.

Colours and typeCopy Anchor Link

A tile paints with the app's own CSS variables, so it follows every theme, dark and light. These 11 are the ones a tile may rely on: each keeps its name and has a value in every theme. Any other --color-* or --font-* in the app may change without notice.

A release that removes or renames one says so with Breaking: in the CHANGELOG.

A tile's code runs in the app's own page, so it gets the browser rights the app uses and no others: notifications and writing to the clipboard. The camera, the microphone, the location and reading the clipboard are refused. A page that needs them goes in a Browser tile, which asks you: host.openUrl(url).

Ids, opening and reinstallingCopy Anchor Link

A tool package's id is @owner/name. Each tool in it has a full id, @owner/name/<key>: hive plugins list --kind tool prints it.

hive ctl open-tool @acme/prs                       # the package's tool, when it has one
hive ctl open-tool @acme/prs/prs                   # by its full id; needed when it has several
hive ctl open-tool @acme/prs --state '{"tab":"open"}'   # the tile's first state

--state is a JSON object: each key is what useTileState(hm, key, initial) reads when the tile first draws.

Installing a tool again with the same code, byte for byte, keeps it on or off as it was. Changed code is switched off, since turning it on trusted the code that was there: switch it on again with hive plugins enable tool:<id>. The install says which.

Running programsCopy Anchor Link

host.run(bin, args, { maxAgeMs, stdin }) runs a program and answers { code, stdout, stderr }.

• bin is a program's name, found on the app's PATH, which comes from your login shell. A folder on PATH inside the tile's own folder is skipped.
• It runs in the tile's folder, without a shell: args reach it as they are, with no globs or pipes. On Windows a .cmd or .bat shim is refused, since only a shell can run one.
• It is stopped after 60 seconds, and when it writes more than 10 MB.
• maxAgeMs (up to 5 minutes) answers the same call from a cache while it is that fresh.
• stdin is text written to its input.

Show a server on this machineCopy Anchor Link

A tool can show a page its own local server serves, such as a dev server or a dashboard. Use Frame from sdk.js:

import { Frame } from "hm-plugin://host/sdk.js";

h(Frame, { src: "http://127.0.0.1:5173/", title: "Dev server" });

Only http://127.0.0.1:<port> and http://localhost:<port> can be shown; any other address is blocked, and the tile stops and says so. Frame runs the page's scripts, forms and popups, and never lets it move the app's window. It gets no camera, microphone, location or notifications: a page that needs them goes in a Browser tile, which asks you.

Look at it, and see what brokeCopy Anchor Link

hive ctl tile look <tile> --json   # a picture of the tile, its state and its console
hive ctl plugin list --json        # each plugin's state: starting, ready or failed, with why

tile look brings the tile into view, waits until its code has drawn, and saves a PNG of it. It answers the tool's state, whether it drew, and the last 100 lines its code wrote to the console. When something is drawn over the tile, such as a pinned tile, a dialog or a notification, it refuses with OCCLUDED and names it; move it, or wait for the notification, and look again.

When the tool's code throws an error nothing catches, a promise of its fails unheard, or the app blocks something it loads, its tile stops and shows why, and plugin list reads it as failed with that reason.

Pointer and keys in a tileCopy Anchor Link

What the canvas does with input over a tool's tile, so your tile can count on it:

Commands agents can runCopy Anchor Link

Declare them in hivemind-tool.json, and answer them in the tile:

"commands": [{ "name": "list", "description": "Every worktree, with its branch and what is not committed." }]

useEffect(() => hm.onCommand("list", () => trees), [hm, trees]);

hive ctl plugin call @dip497/worktrees list prints what the handler returns. It works while a tile of the tool is open. With two open, name one with --tile.

A service that keeps runningCopy Anchor Link

A tool can bring a program the app keeps running while the tool is on: an orchestrator, a dashboard, a watcher. It drives workspaces through the API, with its own token.

"service": { "command": ["node", "service.js"], "role": "agents" }

role is one of the roles. Once switched on, the service waits until you pick the workspaces it may drive, on the tool's page. Where hive host runs it, use hive plugins workspaces tool:<id> <folder>. It then starts with these variables:

It restarts after a crash (after 1 s, then 2, 4… up to a minute). It stays stopped after a clean exit, or when its token is revoked. It should exit when its standard input closes. Its output is on its page.

On a shared canvasCopy Anchor Link

A guest sees a tool's tile if they have the same tool switched on. A tile's programs run on the computer of the person looking at it.

CommandsCopy Anchor Link

hive plugins new tool <name> [--dir folder]   # a starter, with PROMPT.md and its types
hive plugins check <folder>                    # its types, its manifest, and each tile drawn once, with file:line
hive plugins api --kind tool                   # tile, host and hm, as declared
hive plugins install <folder>|@owner/name       # new or changed code off: hive plugins enable @owner/name
hive plugins list --kind tool                  # each tool, and the full id of each of its tiles
hive plugins remove @owner/name

Last validated for Hivemind 2026.10.3.