Add your own agent
Teach Hivemind a coding agent it does not know yet, with one agent.yaml file: how to start it, read its screen and answer it.
Add an agentA coding agent's own program running in a tile, which Hivemind reads and answers.Glossary → when you use a coding agent's program that HiveHub does not list yet. You write one file, agent.yaml. No code and no rebuild.
Paste this into your coding agent to write an agent file for a program you use, check it on the real program, and offer it to everyone.
Show the prompt
Write a Hivemind agent file (`agent.yaml`) for a coding-agent program on this computer, check it against the real program, and, if I want, offer it to everyone. 1. Probe the real program first. Never guess one agent from another. Ask me which program it is. Find it with `command -v`, then run its `--version` and `--help`, and `--help` on its main subcommand. Read its own docs too. For each of these, write down the answer and the line or page that says so, or "could not find it": - how a task is passed: as an argument, or typed into its screen; - whether it has hooks that run when it finishes replying, or before a tool runs, and whether a hook can block; - where it keeps sessions, and how to resume one; - what its screen shows while it works, when it asks permission, and when it asks a question; - which keys allow, deny, or pick an option on those screens. 2. Write `~/.config/hivemind/agents/<id>/agent.yaml` from the "agent.yaml reference" page: `manifestVersion: 2`, an `id` equal to the folder name, `bin` as the bare program name (never a path), and every field under `caps`. Claim a capability only if step 1 proved it. `turnSignal: true` and `supervise: broker` need `launch.hcp` and a hook file beside the manifest. `resume` other than `none` needs `session.resume`. Regular expressions are not allowed in `detect.rules`. 3. Check it: `hive agents validate <folder>`, until it passes. Then `hive agents install <folder>`, and check `hive agents list` shows it with no problem. 4. If Hivemind is open, try it: `hive ctl spawn --agent <id> --prompt "list the files here"`. Watch `hive ctl agents`: it must read working while the agent works, and waiting when it asks permission. `hive ctl stream <tile> --snapshot` shows its screen. If you set answer keys, check each with `hive ctl keys` on a real question. 5. Offer it to everyone only if I say so. New agents are listed by pull request to the GitHub repository dip497/hivemind-plugins, in `agents/<id>/` with a `README.md`. Use my GitHub account through `gh`; if `gh` is not signed in, ask me to sign in myself. At the end, show me the file. Say which capabilities you proved and from where, which you left off and why, and the pull request link if you opened one. REFERENCE https://hivemind.griiken.com/guide/agent-providers.md
Before you start
- Hivemind is installed. See Install and run your first agent.
- The agent's own program is installed and on your
PATH. - You have read its
--help. Everything you claim in the file must come from the real program.
An agent file starts a program in your terminal, with your permissions. There is no sandbox. Before
you install someone else's, read its bin and spawn, and install only agents whose author you
trust.
Write the file
Learn what the program can do
Run <program> --help and read its docs. Write down how it takes a task, whether it has hooks,
and where it keeps sessions. Then note what its screen shows while it works and while it waits
on you.
Check: you have an answer, with a source, for each. "Could not find it" is an answer.
Make the folder
The folder name is the agent's id:
mkdir -p ~/.config/hivemind/agents/acmeWrite agent.yaml
Start small. Claim only what you proved in step 1:
manifestVersion: 2
id: acme
label: Acme Coder
bin: acme-coder # the program's name on your PATH, never a path
enabled: true
caps:
promptDelivery: typed # typed into its screen; argv if it takes the task as an argument
turnSignal: false # true only with launch.hcp and a hook file
resume: none
supervise: human # it has its own permission questions
blockedDetection: true
detect:
default: idle
rules:
- when: { contains: "approve this?" }
then: blocked
- when: { line: [{ gerundAfterPrefix: ["braille"] }] } # "⠋ Reading files…"
then: workingEvery field is described in the agent.yaml reference.
Validate it
hive agents validate ~/.config/hivemind/agents/acmeCheck: it passes. If not, it names each field it refuses. Fix them and run it again.
Install it
hive agents install ~/.config/hivemind/agents/acmeCheck: hive agents list shows acme, on, with no problem.
Check it worked
-
Start it in the open app:
hive ctl spawn --agent acme --prompt "list the files here" -
Watch its tile. While it works, the tile shows working.
-
Give it a task that needs permission, such as editing a file.
Check: its tile turns amber and shows needs you, and the bell in the Layers panel counts it.
hive ctl agents shows the same status.
If it didn't
| You see | Do this |
|---|---|
hive agents validate refuses a capability | You claimed something that needs wiring. Add the block it names, or set the claim to false / none. |
| The tile stays idle while the agent works | Add a detect rule for what its screen shows while it works. Capture the real screen with hive ctl stream <tile> --snapshot. |
| A permission question reads as finished, not needs you | Add a blocked rule for that screen, and set blockedDetection: true. |
| Something else | Troubleshooting |
Where agent files live
| Folder | Used for |
|---|---|
~/.config/hivemind/agents/<id>/agent.yaml | your agents, in every workspace |
<repo>/.hivemind/agents/<id>/agent.yaml | agents a repository ships for everyone who opens it |
A repository can only add agents. It can never change what an id you already have runs.
hive agents list # every agent, where it came from, and why any is unavailable
hive agents remove acmeShare it
Agents are listed on HiveHub by pull request: see Publish an agent.
Once it is merged, hive agents install acme works for everyone.
Related
- agent.yaml reference: every field.
- Run agents: install, start and put agents to sleep.
- Plugins: the other kinds of plugin.
Last validated for Hivemind 2026.10.3.