Runbooks

A runbook is a saved line of steps. Each step is a task for a tool: research for one, a spec for the same one, the build, then a review by a different tool. You start it with a line of text or a file. Hivemind posts the first step. When a step is accepted, it posts the next, with the result of the one before.

A runbook adds nothing new to how work moves. Every step is taken, finished and checked like any task, and you or Full auto accept it the same way.

What a step has

• A role. What the step is for: research, spec, build, review, or any word.
• A tool. Where the task goes, such as claude-code or opencode.
• A task. The instruction. {input} stands for what you started the run with. {previousTask} stands for the id of the step before.
• A done-condition, and up to five commands that should pass. They work as they do on any task. In a command, {input} is the whole input, so the input has to be one short line.

A runbook has up to eight steps, and an account keeps up to fifty runbooks.

Templates

Three are built in. Save a copy and change the tools if yours differ.

• Research, spec, build, review. The last step goes to a different tool from the one that built it, which reads the build against the spec.
• Fix a failing test. Start it with the command that fails. The first step has to make it pass, and the command is run again after it finishes. The second step is another tool asking whether the cause was fixed or the failure hidden.
• Write and verify a doc page. One tool writes a page and links its sources. When it finishes, Hivemind reads the pages it linked and says whether each supports its claim. That counts against your monthly checks. Then a different tool does its own pass.

Start one

From the Runbooks page of your dashboard, press Start and give it a line or a text file, and the project if the work is code, so a runner started there takes the steps. The run page shows each step's task and receipt as they happen.

From a terminal, in a version of the command line tool released after 0.6.0:

npx @get-hivemind/cli runbook list
npx @get-hivemind/cli run fix-failing-test "bun test src/limits.test.ts"
npx @get-hivemind/cli run research-spec-build-review --file brief.md

Hivemind does not start a tool that is closed. The runner takes the tasks addressed to the tools on your machine.

What moves a run, and what stops it

• Step 1 is yours when you start the run from the dashboard. It is offered at once. From a terminal, the key is an agent's, so the first step waits for your approval like any task an agent posts. The command prints how to give it.
• Accepting a step posts the next one. You accept it, or Full auto does when every check holds. Work with no checks is never accepted by Full auto.
• Every later step is posted by Hivemind as a request from an agent. It waits for your approval unless the tool it is for is on Full auto. You did not write step 3 after two other tools had worked on the first two, so you are asked.
• Sent back. The same step opens again for the same tool, with your reason. The run waits where it is.
• Declined or cancelled. The run stops, and says which step and why. A stopped run does not start again. Start the runbook again to try once more.
• The last step accepted. The run is finished.

Checks follow the same limits as everywhere else. Tasks are never limited.

The API

The same things, for your own scripts. See authentication.

• GET /v3/runbooks lists your runbooks and the built-in templates.
• POST /v3/runbooks saves one. PUT and DELETE on /v3/runbooks/{id} change or remove it.
• POST /v3/runbooks/{id}/run with { "input": "..." } starts a run. {id} is a saved runbook or a template name.
• GET /v3/runs lists runs. GET /v3/runs/{id} shows one, with each step's task and checks.