Hivemind
Download
Get startedUse HivemindHow it worksExtendHiveHubAPIReferenceHelp

Connect and call

Build a small client with the TypeScript or Python SDK: connect with your token, start an agent, read its reply, answer it, and hear events.

Open
Open in GitHubView as MarkdownOpen in ClaudeOpen in ChatGPTOpen in CursorOpen in Scira AI

In this tutorial you build a client that lists your agents, starts one, reads its reply, answers its questions and follows what happens. It takes about ten minutes.

Paste this into your coding agent to make a token and write a client with the hivemind-api SDK.

Open in…
Open in ClaudeOpen in ChatGPTOpen in CursorOpen in Scira AI
Show the prompt
Make a Hivemind API token and write a small client with the `hivemind-api` SDK that connects to my workspace, starts an agent, reads its reply and prints the events it hears.

1. Ask me which workspace folder to drive, whether I prefer TypeScript (Node 20 or newer, or Bun) or Python (3.9 or newer), and whether the client only reads (`view`) or also starts agents (`agents`).
2. Check Hivemind runs with the folder open: `hive ctl agents` must not exit 3. If it does, ask me to run `hivemind <folder>`.
3. Make the token: `hive grant create api-client -w <folder> --role <role> --expires 7d --json`. Keep the token out of this chat and out of git: write `HIVE_DRIVE_TOKEN`, `HIVE_DRIVE_SOCK` (the `socket` field) and `HIVE_WORKSPACE` (the folder) to a git-ignored `.env`.
4. Install the SDK that comes with the app. On macOS or Linux: `npm install ~/.hivemind-app/sdk/hivemind-api.tgz` or `pip install ~/.hivemind-app/sdk/python`. On Windows: `npm install %LOCALAPPDATA%\hivemind\sdk\hivemind-api.tgz` or `pip install %LOCALAPPDATA%\hivemind\sdk\python`. Only on a computer without Hivemind, install it from the release, where <version> is the version of the app my program talks to: `npm install https://github.com/dip497/hivemind/releases/download/v<version>/hivemind-api-<version>.tgz` or `pip install https://github.com/dip497/hivemind/releases/download/v<version>/hivemind_api-<version>-py3-none-any.whl`.
5. Write the client. `connect()` reads the token, workspace and socket from those variables. Print `hive.as` (Python: `hive.as_`), then `hive.agents.list()`.
6. With an `agents` token: `hive.agents.start` with program set to an agent from `hive agents list` and prompt "Say hello", then `hive.agents.read` the tile. If `finalStatus` is `waiting`, show me what it asks and answer only after I say so, with `hive.agents.answer(tile, reply.waiting.since, ...)`.
7. Print `agent.event` events with `hive.on`. Catch `ApiError` and print its `code`.
8. Run it for 30 seconds and show me what it printed.

At the end, tell me the token's id from `hive grant list` and how to revoke it: `hive grant revoke <id>`.

REFERENCE https://hivemind.griiken.com/guide/api-connect.md

What you'll learn

  • How a program says who it is, with a token.
  • How to start an agent, read its reply and answer it.
  • How to follow what your agents do, as it happens.

Before you start

  • Hivemind is running with your project open.
  • Node 20 or newer (or Bun), or Python 3.9 or newer.
  • A token for that project, made as in Make an API token. Use agents to follow every step here; view reads only.
  • The token in your environment, never in your code:
export HIVE_DRIVE_TOKEN=hgr_…                          # from hive grant create
export HIVE_WORKSPACE=~/work/api                       # the project folder
export HIVE_DRIVE_SOCK=~/.config/hivemind/drive.sock   # the socket it printed

Install the SDK

The SDKs come with Hivemind, at the same version as the app.

npm install ~/.hivemind-app/sdk/hivemind-api.tgz
pip install ~/.hivemind-app/sdk/python

The Python package uses only the standard library.

Connect

connect() reads the token, the workspace and the socket from the variables above. Without them, it uses this computer's app.

import { connect, ApiError } from "hivemind-api";

const hive = await connect();
// or: await connect({ token: "hgr_…", workspace: "/home/you/work/api", socket: "…/drive.sock" })
console.log(hive.as);

Check it worked: it prints your token's name, role and workspace:

{ client: "dashboard", role: "agents", workspace: "/home/you/work/api" }

List the agents and start one

const { agents } = await hive.agents.list();
console.log(agents);

const { tile } = await hive.agents.start({ program: "claude", prompt: "Run the tests" });

Check it worked: a new agent tile opens in the app. program is an agent from hive agents list.

Read the reply, and answer a question

agents.read waits for the agent to finish replying. If it stops to ask you something, answer it.

const reply = await hive.agents.read(tile, { timeoutMs: 600_000 });
if (reply.finalStatus === "waiting") {
  await hive.agents.answer(tile, reply.waiting!.since, { decision: "allow" });
}
console.log(reply.text);
finalStatusMeans
turnThe reply is in text.
timeoutIt is still working. Read again.
workingRead with timeoutMs 0: it is still working.
idleIt was sent nothing since you last read it, and is not working. Send it a task.
waitingIt asks you something. Answer with agents.answer: allow or deny a permission, or {text} for a question.
closedIts tile was closed.

Check it worked: the agent's tile turns amber while it waits, then goes back to work after your answer.

Listen to events

const off = hive.on("agent.event", (repo, event) => console.log(event.kind, event.tile));
// later: off();
EventTells you
agent.changedAn agent appeared, changed or went.
agent.eventAn agent finished replying (turnEnded), started waiting on you (waiting), was answered, or reported.
status.changedAn agent's status changed.

Check it worked: start an agent in the app. Your client prints came.

Handle errors

Every refusal is one ApiError with a code. call runs any method by name.

try {
  await hive.call("agent.start", [hive.workspace!, { program: "claude" }]);
} catch (e) {
  if (e instanceof ApiError && e.code === "FORBIDDEN") console.log("this role may not start agents");
}
hive.close();

Check it worked: with a view token, it prints the refusal. The codes are listed on Protocol.

For Python with asyncio, import from hivemind_api.aio: async with await connect() as hive:. The methods are the same, awaited.

What the SDK gives you

Both SDKs have the same shape: as (Python as_), workspace, call(method, params, timeout), notice, on(event, fn) that returns off, closed and close(). Helpers:

HelperMethods
agentslist, since, start, read, send, answer, output, interrupt, close
framesopen, close
terminalswrite, close

Everything else is on Methods by role, through call.

Other languages: see Protocol for the raw messages.

What you did

  • Your program proved who it is with a token, at one role.
  • It started an agent, read its reply and answered its question.
  • It followed your agents through events, and handled a refusal.

Next

  • Methods by role: everything else you can call.
  • Revoke the token when you are done: hive grant revoke <id>.

Last validated for Hivemind 2026.10.3.

Edit on GitHub

Make an API token

Make a token so one of your programs can drive a workspace, choose its role, and revoke it when you are done.

Methods by role

Every method a program's token can call, grouped by the smallest role that allows it, with its params and an example.

On this page

What you'll learnBefore you startWhat the SDK gives youWhat you didNext