adding-an-agent-provider
Skill17 starsChanged 12 days agoMITView on GitHub
Add a new CLI coding agent (gemini, amp, cursor, …) to hivemind end to end — capability research on the real binary, ONE agent.yaml manifest published to the HiveHub registry (dip497/hivemind-plugins), and the lifecycle proof that decides when it is actually done. Use when adding a new agent, completing a half-wired one, or reviewing a PR that does either.
- Reads credentials
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- guide/AGENTS.mdAGENTS.md
- spec/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ascii-character-animationSkill
- feature-doneSkill
- hive-browserSkill
- hivemind-custom-viewSkill
- hivemind-live-wallpaperSkill
- maintaining-docsSkill
- test-auditSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 47
"I could not find it" is a valid answer: Write it that way. Never write "X does not exist" unless you looked and can say where you looked.
- Distinctive: line 50
Never infer a capability from another agent's shape.
- Very specific: line 60
When docs are thin, read the shipped package: ls -l $(readlink -f $(which <bin>)), then grep its dist/ for flag strings.
- Very specific: line 170
If the agent can end a turn with work running that wakes it when it finishes, say how many with awaiting on turn.ended: its tile stays …
- Very specific: line 178
When the agent's permission hook can print the decision, declare answer: on its input.requested entry (spec/needs.md 0.9.
- Very specific: line 194
If you find yourself naming the agent anywhere else — in UI code, in the CLI, in a provider list — stop: that is a hardcoded provider, and …
- Very specific: line 235
Declaring an absence you did not verify: Run --help, read the docs page, then write it — with the source.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Adding an agent provider
Why this exists
An agent is one manifest — agent.yaml, plus the hook asset it ships if it injects
hooks or resumes. That is not where agent PRs go wrong. They go wrong one step earlier — in
what the author believed about the CLI.
A real example: a PR added an agent and stated "no hook system exposed, status is
screen-scrape only". That CLI ships agentSpawn / userPromptSubmit / preToolUse /
postToolUse / stop hooks with a JSON stdin contract and a blocking exit code — the
same shape hivemind already consumes for claude. Nobody had run --help. The result
would have shipped as a "fully-wired agent" that silently cannot be driven.
Today the capabilities you declare are what the control plane believes: declare
turnSignal: true for a runtime that never reports a turn and hive ctl read times
out on it; declare false and hive ctl workflow --agent <id> refuses up front with
exit 7. A wrong capability is a wrong contract. This skill is the procedure that
makes the declaration true: research first, tier second, manifest third, and a lifecycle
proof that says out loud what works.
The rule
An agent is done when a human can drive it on the canvas and the control plane
can drive it as a worker. If you can only reach the first, that is a legitimate PR —
but it ships with turnSignal: false and a note, so the UI, the CLI and HCP all
say so, never silently.
Nothing agent-specific is compiled into the app. Agents are published to the HiveHub registry and added to a user's machine automatically when their CLI is found. The authoring format for a PR is the same format a user writes by hand — a manifest cannot do anything a user's own file cannot.
Phase 1 — Probe the CLI (never skip, never infer)
Three rules:
- Probe the binary that is actually installed.
--helpbeats memory, every time. - Cite a source per answer — a doc URL, a
--helpline, a file you grepped. - "I could not find it" is a valid answer. Write it that way. Never write "X does not exist" unless you looked and can say where you looked.
Never infer a capability from another agent's shape. Two CLIs that look alike in the TUI can differ completely in hooks, session storage, and shell access.
which <bin>; <bin> --version; <bin> --help
<bin> <subcommand> --help # chat/run/agent — whatever the entry command is
npx ctx7@latest library "<Product> CLI" "<your question>"
npx ctx7@latest docs /<org>/<project> "hooks, session resume, running shell commands"When docs are thin, read the shipped package: ls -l $(readlink -f $(which <bin>)),
then grep its dist/ for flag strings. Finish with one adversarial search per topic.
The capability probe → the caps you will write
Answer all eleven with a source. Each answer decides a field of the manifest.
| # | Question | Decides |
| 1 | Exact binary name. Same-named binary from a different product? | bin; aliases (identification only — a bare kiro is the Kiro IDE) |
| 2 | Does the bare binary start an interactive session? Default subcommand? | bin / spawn.args |
| 3 | Positional prompt (<bin> "do X")? Stays interactive afterwards? | caps.promptDelivery: "argv" or "typed" |
| 4 | Permission / trust model. Per-tool prompts? Flags to pre-trust? | spawn.args (match the agent's own safe default); caps.supervise: "human" if it has prompts, "none" if it has no permission system at all |
| 5 | Hook / event system: events, stdin shape, exit-code semantics, can a hook block? | caps.turnSignal; "broker" supervise if a pre-tool hook can block (launch.hcp + the hook asset) |
| 6 | Session ids: assignable at spawn? discoverable after? resume by id or cwd? | caps.resume and the session block (bind / resume) |
| 7 | Config-home override env var (FACTORY_HOME_OVERRIDE, KIRO_HOME, …) | whether a home overlay can inject config without touching the user's real home |
| 8 | Can the agent run shell commands + inherit the spawn env? | whether the worker can call hive ctl report (needs hive on PATH + HIVE_HCP_SOCK/HCP_TOKEN/HIVEMIND_TILE from the env) |
| 9 | --model flag? claude-style permission modes? | the options block (model, mode) |
| 10 | What the TUI prints while working, and while waiting for approval | the detect rules and caps.blockedDetection — capture real output, do not guess |
| 10b | Which rows above its input are its own chrome (spinner, timer, status bar, what a turn's end says) | detect.chrome, so a tile's last line shows what it said — capture real rows, do not guess |
| 11 | Which keys allow and which deny its own permission prompt | the answer.permission block (the phone's Allow / Deny types them) — read them from the binary's chooser, or leave the block out |
| 11b | Which keys choose an option of a question it asks (AskUserQuestion's chooser) | choose with {n} (the phone's option buttons type it) and asks under the transcript's tool — read them from the binary's chooser, or leave them out |
| 12 | Which key interrupts its turn (the "esc to interrupt" hint) | interrupt (the phone's Stop types it) — read it from the binary's own hint, or leave it out |
| 13 | Does its session file keep what was said, a JSON record a line? Which records and fields? Does its own program write text there as if the person typed it? | session.transcript (the phone's conversation), its notices for what its program wrote — map a real session file's records, check the mapping against conformance/conversation.json's rules, or leave it out |
Row 10 needs a real run. If you cannot install the CLI, say so and set
blockedDetection: false rather than inventing prompt text — a wrong detector is
worse than a missing one, because it reports the wrong state confidently. Rows 11 and
12 the same: a wrong key allows what the person denied, or quits the agent instead of
stopping its turn (Ctrl+C twice ends some CLIs), so with no evidence, leave answer
and interrupt out: the phone answers that agent with text, and offers no Stop.
Phase 2 — Pick the tier
Take the highest tier the probe supports. Tier 0 for an agent that has hooks means the probe was wrong — go back to Phase 1.
| Tier | The CLI gives you | Declares | Copy from |
| 0 — raw | nothing but a TUI | turnSignal: false, resume: "none", a note | the opencode published manifest |
| 1 — resume | discoverable session files/ids | + resume: "cwd", a session.resume block | the codex published manifest |
| 2 — injected runtime | a config-home override or an extension loader | + turnSignal: true, wiring launch.hcp with the hook asset | the droid (overlay) / pi (extension) manifests |
| 3 — native | pre-assignable session id + blocking permission hook | + resume: "tile", supervise: "broker" | the claude / kiro manifests |
The published manifests live in
packages/hive-agents/tests/fixtures/published-agents/<id>/ — they are the exact files
the registry serves, so they are both reference material and fixtures.
Tier 2 is the important line: below it the agent cannot report back, and the
manifest says so — hive ctl workflow refuses it and hive ctl read answers
UNSUPPORTED.
Phase 3 — Write the manifest (one directory)
The agent is one folder: agent.yaml plus, for tier 2+, the hook/overlay asset it
ships beside it. See
the manifest guide for the full
field reference; claude/agent.yaml in the published fixtures is the richest example.
id— one bare name (lowercase, digits, dashes). Ids Hivemind has shipped are reserved for the command they have always launched: taking the name for another binary is refused when the manifest is read.caps— every field is required; claim a tier-2/3 capability only with the wiring that delivers it (see Phase 2).options— what Settings lets the user choose at launch;modelandmodeare whathive ctl spawn --model/--modeset.detect— ordered rules over the rendered screen; the first match wins.detect.chromeis one test of a single row: the rows of its own chrome, which a tile's last line skips.icon— shapes, not SVG markup;viewBox+path/rect/circle/ellipse.hooks.events— map each native hook event to a canonical event withemit:, not to a script. The vocabulary issession.started,session.ready,session.ended,turn.started,turn.ended(+outcome: done | failed | interrupted | limited),input.requested(+kind: permission | question | plan | approval | other),input.resolved,subagent.started,subagent.stopped,compacting.started,compacting.ended— specified inspec/agent-event.schema.json, and how they fold into a status inspec/status.md. Use the agent's ownmatcherto split one native event (Claude'sStopFailurewithmatcher: rate_limit→outcome: limited). Mapinput.resolvedtoo (e.g.PostToolUse), or a tile answered in the agent stays "needs you" until the turn ends. One generic script reports them and never forwards text the agent wrote. Map an event only after seeing the real binary fire it, and inject per launch — never write the user's global config. When the agent's turn-end payload carries the turn's reply (Claude's and Codex'slast_assistant_message), name that field withreply:on theturn.endedentry (it needslaunch.hcp): the same generic hook hands it over before the turn end, natively, with no script of the plugin's.Anything data cannot say is a script the plugin ships, never code in the host: list it in
assetswith ahook:name (andproduces:for the events it reports), and name that hook inevents. It loads the host's SDK —const hive = require(process.env.HIVE_SDK)— forpayload(),emit(),reportReply(),requestApproval()andopenPlanReview()(packages/agent-sdk, wire format inspec/hook-protocol.md). The replyhive ctl readreturns comes fromreply:when the payload carries it, else fromreportReplyreading the agent's own transcript (Droid). An agent whose hook config is a file of its own shape uses{emit:turn.ended}/{hookCmd:<name>}placeholders inside that asset.events: UserPromptSubmit: { emit: turn.started } Stop: { hook: turnEnd } # the plugin's script: reads the reply, reportReply, then emit turn.ended StopFailure: { emit: turn.ended, outcome: failed } PermissionRequest: { emit: input.requested, kind: permission } assets: - { name: hive-turn-end.cjs, file: hive-turn-end.cjs, hook: turnEnd, produces: [turn.ended] }If the agent can end a turn with work running that wakes it when it finishes, say how many with
awaitingonturn.ended: its tile stays working until a turn ends with none (spec/status.md). Count nothing that has no end, or the tile never comes back. A task the agent's own screen can stop with no hook firing still ends, after a quiet spell.An app older than
emitrefuses such a manifest, so publishing one needs the registry to carry aminAppVersionfor agents.When the agent's permission hook can print the decision, declare
answer:on itsinput.requestedentry (spec/needs.md0.9; Claude's is in the fixture manifest): the hook then holds until the phone answers, and nothing is typed. Probe first that the agent's own prompt is still drawn while the hook runs. Codex 0.162 draws its prompt only after the hook returns, so a held hook leaves the desktop nothing to answer, and Codex stays on keys.
Try it before you publish: drop the folder into
~/.config/hivemind/agents/<id>/ (or run hive agents install ./<id>) — the running
app picks it up, hive agents list shows it with any validation error, and nothing
needs a rebuild.
Publish: one pull request to dip497/hivemind-plugins adding the folder to the registry. Once merged, every machine with the agent's CLI gets it automatically, and the site's agent strip picks the icon up from the published manifest.
If you find yourself naming the agent anywhere else — in UI code, in the CLI, in a
provider list — stop: that is a hardcoded provider, and no-hardcoded-providers.test.ts
will find it.
Phase 4 — Tests
hive agents validate ./<id> # what a user will be told about it
cd apps/desktop && npx electron-vite build # then drop it in and launch the apphive agents list— the agent appears, with its CLI found (or the reason it is not).- Settings ▸ Plugins (the agent's row, then its page) — the card shows the launch options, the install link if the CLI is missing, and the capability note if it is not a worker.
- The e2e suite runs the full lifecycle for a throwaway manifest
(
apps/desktop/tests/e2e/zz-sixth-provider.spec.ts) — read it before claiming done.
Phase 5 — Prove the lifecycle
Fill checklist.md (next to this file) into the PR description. Every row gets
✅ / ❌ / N/A with a one-line note — no blanks. A row you did not test is ❌.
For a real runtime, run it by hand, in order:
- Spawn from the frame launcher → the tile starts and shows working, then idle.
hive ctl sendto it mid-turn → the message lands at its prompt, not mid-render.hive ctl readfrom another agent → returns the reply, notfinalStatus:"timeout".hive ctl spawn(report on by default) → the worker's reply reaches the spawner once.- Trigger a tool-approval prompt → tile status is waiting, notification says Needs your input.
- Kill the PTY daemon, relaunch → the tile restores into its own prior session.
- Close the tile → no leaked state, no hung reader.
Anti-patterns
- Declaring an absence you did not verify. Run
--help, read the docs page, then write it — with the source. - A capability that is a wish.
turnSignal: truebecause the hooks should work. Prove it with row 3 above before you ship it. - Matching a binary that belongs to another product.
kirovskiro-cli. - Wiring claimed without the asset.
turnSignal: truewithoutlaunch.hcpplus the hook file is refused — and should be. - Naming the provider in product code. Agents are data; the UI, the CLI and HCP read
manifests.
no-hardcoded-providers.test.tsfails on any exception. - Default-on trust flags (
--trust-all-tools,--yolo). Match the agent's own safe default; the human on the canvas answers prompts. - Skipping the CHANGELOG (
## [Unreleased]— the release notes are cut from it).
When the agent cannot be a worker
Tier 0 and 1 ship with turnSignal: false and a note. The catalog then does the
telling: the UI shows the note, hive ctl workflow --agent <id> exits 7 with it,
hive ctl read on its tile answers UNSUPPORTED. Wording that works:
"scrape-only status and no turn signal — drive it by hand on the canvas;
hive ctl read / hive ctl workflow cannot gather from it."
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

