Protocol

The messages behind the SDKs, for writing a client in any language. This page reflects workspace API version 0.30.

Using the messages on this page, write a client for the Hivemind workspace API in the language I name.

1. Ask me for the language and the workspace folder. Make a token with the smallest role it needs: `hive grant create <name> -w <folder> --role view --expires 7d --json`. Keep the token out of this chat and out of git: read it from the environment variable `HIVE_DRIVE_TOKEN`, with `HIVE_DRIVE_SOCK` and `HIVE_WORKSPACE`.
2. Connect to `HIVE_DRIVE_SOCK` (a Unix socket on Linux and macOS, a named pipe on Windows). Within 10 seconds send one line: `{"hello": {"token": "<token>", "workspace": "<folder>"}}`.
3. Send calls as one JSON line each, `{"id": n, "method": "...", "params": [...]}`. Match answers by `id`; they can come out of order. A line without an `id` is an event, or a JSON list of events.
4. Handle every error code in the table on this page.
5. Call `agent.list` for the folder, print the result, then print events for 30 seconds. Show me the output.

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

Find the socketCopy Anchor Link

hive grant create prints the socket's path (socket with --json). By default it is:

The app or hive host must be running, with the workspace open.

MessagesCopy Anchor Link

Every message is one line of JSON, both ways.

HelloCopy Anchor Link

Send this within 10 seconds of connecting:

{"hello": {"token": "hgr_…", "workspace": "/home/you/work/api"}}

workspace is the workspace's folder. Leave it out when the token reaches only one workspace.

Calls and answersCopy Anchor Link

A call has an id you choose, a method and a list of params. Its answer has the same id, and either a result or an error:

{"id": 1, "method": "agent.list", "params": ["/home/you/work/api"]}
{"id": 1, "result": {"seq": 0, "agents": []}}

{"id": 2, "method": "agent.start", "params": ["/home/you/work/api", {"program": "claude", "prompt": "Run the tests"}]}
{"id": 2, "error": {"code": "FORBIDDEN", "message": "agent.start is not open to your role on this workspace"}}

Where a method takes a folder (repo), give the workspace's folder. Answers can come out of order, so match them by id.

EventsCopy Anchor Link

A line without an id is an event, {"event": "…", "params": [...]}, about the workspace's tiles. Several events from one moment may arrive as a JSON list on one line.

• agent.changed: an agent appeared, changed or went.
• agent.event: an agent finished replying (turnEnded), started waiting on you (waiting), was answered (answered), came, went, or reported.
• status.changed: an agent's status changed.
• terminal.data: output of a terminal you opened.
• tile.lines: the last line of terminals you watch (tile.watchLines) changed, at most every 250 ms.
• file.changed: files changed in the workspace.

Error codesCopy Anchor Link

A whole exampleCopy Anchor Link

This connects, lists the agents and tries to start one. With a view token the start is refused. Both run on Linux and macOS, over a Unix socket.

import json, os, socket

SOCK = os.environ["HIVE_DRIVE_SOCK"]
TOKEN = os.environ["HIVE_DRIVE_TOKEN"]
FOLDER = os.environ["HIVE_WORKSPACE"]

s = socket.socket(socket.AF_UNIX)
s.connect(SOCK)
f = s.makefile("rw")

def send(msg):
    f.write(json.dumps(msg) + "\n")
    f.flush()

def call(id, method, *params):
    send({"id": id, "method": method, "params": list(params)})
    while True:
        msg = json.loads(f.readline())
        if isinstance(msg, dict) and msg.get("id") == id:  # not an event
            return msg

send({"hello": {"token": TOKEN, "workspace": FOLDER}})
print(f.readline())                   # {"hello": {"api": "0.30", "as": {…}}}
print(call(1, "agent.list", FOLDER))  # {'id': 1, 'result': {'seq': 0, …}}
print(call(2, "agent.start", FOLDER, {"program": "claude", "prompt": "Run the tests"}))

Start an agent and wait for its replyCopy Anchor Link

With an agents token:

{"id": 3, "method": "agent.start", "params": ["/home/you/work/api", {"program": "claude", "prompt": "Run the tests"}]}
{"id": 3, "result": {"tile": "…"}}
{"id": 4, "method": "agent.read", "params": ["<tile>", 600000]}
{"id": 4, "result": {"text": "…", "finalStatus": "turn", "truncated": false}}

agent.read waits up to the milliseconds you give for the agent to finish replying. finalStatus is turn, timeout, working, idle, closed or waiting. A tile that runs no agent is refused NO_AGENT, and an agent asleep ASLEEP.

The full protocol is spec/workspace-api.md in the repository.

Last validated for Hivemind 2026.10.3.