hivemind / spec
AGENTS.md17 starsChanged 12 days agoMITView on GitHub
The person's agents, as their phone sees and drives them (M5, docs/design/phone-app-2026-10-02.md §4): every agent in the workspaces one of their devices holds, live; and starting one, stopping its turn, closing it, and what it changed. What waits on the person, and answering it, is needs.md's. The cases in ../conformance/agents.json decide whether an implementation follows this. One of the person's devices opens the stream agents on a connection on hive/ws/1 to another of their devices, and sends { "t": "follow"…
- Deletes or force-pushes
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- guide/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adding-an-agent-providerSkill
- ascii-character-animationSkill
- feature-doneSkill
- hive-browserSkill
- hivemind-custom-viewSkill
- hivemind-live-wallpaperSkill
- maintaining-docsSkill
- test-auditSkill
The file
Files
Agents (0.10)
The person's agents, as their phone sees and drives them (M5, docs/design/phone-app-2026-10-02.md
§4): every agent in the workspaces one of their devices holds, live; and starting one, stopping
its turn, closing it, and what it changed. What waits on the person, and answering it, is
needs.md's. The cases in ../conformance/agents.json decide whether an implementation follows
this.
Following
One of the person's devices opens the stream agents on a connection on hive/ws/1 to another of
their devices, and sends { "t": "follow" } on it. The device answers at once with the agents in
the workspaces it holds,
{ "t": "agents", "agents": [ … ], "working": 3 }and answers again, with the whole list, each time it would answer otherwise, until the stream or
the connection closes: the first change at once, and the changes in the next 100 ms together at
its end, so at most ten answers a second, none the same as the one before it. working is how
many of them are at work (needs.md 0.2). Anything else sent on the stream is ignored. Who may
follow is the person's own devices, a phone among them; anyone else is cut off.
Each agent is one with a status (status.md) whose tile is on the board of a workspace the device
holds:
{ "workspace": "<the workspace's id>", "name": "<the workspace's name>", "tile": "<its tile>",
"agent": "<what it is called>", "program": { "id": "claude", "label": "Claude Code" },
"state": "waiting", "since": 1790000000000, "machine": "<the machine it runs on>",
"waiting": { "kind": "permission", "says": "trust", "since": 1790000000000, "plan": "<markdown>", "decide": true },
"interrupt": true, "conversation": true, "session": "<its session's id>" }A supervised agent's wait on its starter (0.5, "kind": "approval") also says what it asks, and the
item who started it:
{ "parent": "client:<grant id>",
"waiting": { "kind": "approval", "since": 1790000000000,
"approval": { "request": "<its id>", "tool": "Bash", "summary": "rm -rf dist",
"expiresAt": 1790000540000 } } }agentandmachineare asneeds.mdgives them (0.3).programis the agent its tile runs, by its manifest's id and label; left out for a tile whose command no manifest here names.stateis its status's state,sincewhen it last changed.waitingis there while it waits with a kind:kind(permission,question,plan,other, orapproval, on the agent supervising it),sincethe same as the state's, andsays(0.5),plan,decide, andtool,asksandchoose(0.7) asneeds.mdgives them for a wait on the person.approval(0.5) is there on anapprovalwait: thetoolit would use, asummaryof what it would do with it (a command, a file, a URL), andexpiresAt, when it stops waiting and the agent asks at its own prompt instead.parent(0.5) is who started it and hears what it reports: an agent's tile, orclient:<grant id>for a program on the drive socket (workspace-api.md, "Drive socket").interruptistruewhen its manifest says which keys interrupt its turn (interrupt), soagent.interruptstops it; left out otherwise.background: how many background tasks its last turn left running, asstatus.mdcounts them. Left out when there are none or its program stopped.conversationistruewhen its manifest maps its session file's records (session.transcript) and says where that file is (session.resume.exists), soagent.conversationcan say what it and the person said to each other ("Conversation"); left out otherwise (0.4). The phone opens an agent without one in its terminal.session(0.6) is the session it is in, as its agent last said:agent.start'sresumegoes on with it. A new one (the person cleared it, or resumed another) changes the item, so a reader followingagent.changedhears it. Left out until the agent says, and kept once it exits.
Agents are in order of their workspace's id, then their tile (by its characters' codes).
A phone keeps each device's list as it last answered, and shows them one device after another;
what waits on the person among them (a waiting whose kind is not approval) it shows as one list,
as needs.md orders it, and the agents at work it adds up. An answer with no list of agents says
nothing; a working that is not a whole number of none or more counts none. An item it cannot read
is left out: one that is not an object, has a field it must have (program, waiting,
interrupt and conversation may be missing) missing or of another type, a state not listed
above, or a waiting that is no object, has a kind not listed or no since. A program that is
not an id and a label, a decide, interrupt, conversation or choose that is not true,
a decide on anything but a permission, a choose on anything but a question, and a waiting's
tool or asks not shaped as needs.md gives them, are taken as not there.
Starting
agent.startable(workspace), a method of the workspace API (workspace-api.md), answers what
may be started in the workspace, which a peer names as hive://<its id>:
{ "programs": [ { "id": "claude", "label": "Claude Code",
"options": [ { "id": "model", "label": "Model", "values": ["opus", "sonnet"] } ] } ],
"frames": [ { "id": "<frame>", "name": "<its title>", "machine": "<the machine its folder is on>" } ] }programs are the agents this device starts (switched on, their command found here); options
are their model and mode choices, as the desktop's settings offer them: those the agent's
command lists (its --help, or its listing command), then those its manifest names; values empty
for one taken as typed. A command that has not answered within 1.5 s adds its own next time.
agent.places lists each machine's agents the same way; a saved machine's command is not asked.
frames are the
workspace's frames, as the board orders them.
agent.start(workspace, start) starts one there, as hive ctl spawn does: start is { program,
frame?, folder?, images?, prompt?, model?, mode?, name?, resume?, supervise?, report? }, program one agent.startable lists, frame one of its frames (none: the
workspace's first frame, or none when it has none), folder (0.8) one of "Places" below, not with
frame, and program then one found on its machine, images (0.8) at most 4 photos { "type":
"image/png" | "image/jpeg" | "image/webp" | "image/gif", "data": "<base64>" } of at most 5 MB
each, kept on the machine it runs on and their paths put after the prompt, a blank line between,
prompt at most 10,000 characters with no
control characters but newlines and tabs, and model, mode, name (its tile's) and resume (a session of its to go on with) lines of at
most 200 characters. supervise (0.5) is true (the tools its manifest says are supervised),
"all", or a list of tool names: before using one it waits on its starter (an approval wait),
which answers with agent.answer. A program that starts it on the drive socket is its starter, and
is told what it reports (hive ctl report): the workspace's readers get an agent.event of kind
reported, unless report is false.
It starts as the person launches it at their desktop, with the options they saved for that agent
and these on top: never in its unattended mode unless mode says so, or an agent on the drive
socket starts it (hive ctl spawn) unsupervised, where no one is at its tile. It answers { "tile":
"<the new tile>" }. Anything else is BAD_REQUEST.
An agent runs its launch (hooks, its tile id) from the manifests installed on the machine it runs
on. A start on another machine carries the agent's manifest folder as the starting machine has it
installed (the daemon's attach takes agent: { id, files }, each file base64, 2 MB at most); a
daemon with no agent of that id installs it first, validated as hive agents install validates
one, and a daemon that has one keeps its own. An agent of a repository is never carried.
Places
(0.8) agent.places(workspace) answers where an agent may be started in the workspace: each
machine its folders are on, this computer first (id ""), then the saved machines by name, with
the agents found there (as programs above) and its folders:
{ "machines": [ { "id": "", "name": "<this computer>", "programs": [ … ],
"folders": [ { "path": "/home/p/api", "name": "api", "kind": "project", "frame": "<frame>" },
{ "path": "/home/p/notes", "name": "notes", "kind": "recent" } ] },
{ "id": "<saved machine>", "name": "build-box", "programs": [], "folders": [ … ],
"unreached": "<why it could not be asked>" } ] }project folders are the workspace's own folder then each frame's, as the board orders them, with
the frame there; recent ones the folders the person opened lately, newest first, those that are a
project's left out. A folder is a path here, or machine://<saved machine>/<path>; one on a
machine not saved, or on a paired device, is not listed. A machine that could not be asked has
no programs and says why in unreached.
agent.folders(workspace, folder) answers the folders in folder, one of the workspace's projects
or inside one, links followed: { "path": "<folder>", "folders": [ { "name", "path" } ], "more"?:
true }, by name, at most 200, those whose name starts with a dot left out, more when there are
more. A folder in none of its projects is FORBIDDEN; one not there is NOT_FOUND.
An agent started in a folder runs in the frame there; when there is none, in one opened for it
inside the innermost project it is in, or at the top for a recent folder. A folder that is neither
is FORBIDDEN, and nothing is started.
Stopping
agent.interrupt(tile) types the keys the agent's manifest says interrupt its turn (interrupt,
tokens as hive ctl keys takes them), a moment apart, while it is working or waiting, and answers
{ "interrupted": true }; { "interrupted": false } when it is doing neither, or has no terminal.
An agent whose manifest says no keys is BAD_REQUEST.
agent.close(tile) ends the agent's session and takes its tile off the board, as hive ctl close
does, and answers { "closed": true }; { "closed": false } when no workspace here has the tile.
Sleep
agent.sleep(repo, target?, force?) puts agents to sleep, as hive ctl sleep does: a tile by its
id or name, else a frame's agents (those of the frames in it too), else every agent of the
workspace. Each one's process ends; its tile keeps its name, the folder it
slept in (sleeping in the layout) and when (sleptAt, ms since epoch). A view sees it asleep
(asleep on its tile in structure, view protocol 1.14). Left awake, each listed with why: an agent working or waiting on
someone (unless force), one whose manifest says no session.resume (it would wake blank), a
shell, and a session started elsewhere. Nothing is typed into a sleeping agent: agent.send to it
is refused, and what other agents send it waits. agent.wake(repo, target?) starts each again in
its conversation, in the folder it slept in; what waited is typed once it says its session started.
Another tile may not start a sleeping agent's conversation, and a sleeper is not woken while
another tile runs it. Both answer { "slept" | "woke": [tile], "skipped": [{ "tile", "why" }] }.
Changes
agent.diff(tile) answers what the agent changed, in the folder it runs in (its frame's worktree's,
else its frame's, else the workspace's), against its last commit:
{ "files": [ { "path": "src/nav.ts", "status": "M", "added": 3, "removed": 1 } ],
"patch": "<a unified diff>", "truncated": false }files are the changed files, by path: status is M (modified), A (added), D (deleted),
R (renamed), C (copied), U (conflicted) or ? (not yet tracked), and added and removed
the lines the patch adds and removes in it. patch is git diff HEAD, followed by each file not
yet tracked as a new file (one over 64 KiB, or that is not text, is listed and not shown), cut at
512 KiB at the end of a line, when truncated is true. A folder that is no git
repository answers no files and an empty patch; one on another machine is FAILED, saying so.
Commands
agent.commands(tile) (0.10) answers the slash commands the agent takes at its prompt, for a
device to offer as the person types /:
{ "commands": [ { "name": "review", "description": "Review the diff", "from": "project" } ] }Its manifest says them (commands): its own (builtIn, each a name and a description), and the
folders it reads more from (folders), each a path under {home}/ (the person's, from
yours) or {folder}/ (the folder the agent runs in, project). In a folder, a command is a
*.md file, a subfolder's name put before its own with : (frontend/component.md is
frontend:component), three folders deep at most; with skills, a folder each, its SKILL.md
saying it, and one whose front matter says user-invocable: false is left out. prefix goes
before each name (prompts:). A command says what it does in its front matter's description, else
in its first line of text that is no heading, cut to 200 characters. A name is a letter or digit,
then letters, digits, _, ., : and -, 64 characters at most; another is left out. One of a
name a later folder lists shadows the earlier, so the project's shadows the person's and both the
agent's own. They come ordered by name, 500 at most. An agent on another machine answers its own
only, its folders being there.
Conversation
A program on the machine the agent runs on may read its session file itself: agent.transcript(tile)
(workspace API 0.32) names it.
agent.conversation(tile, cursor?, session?) (0.2; session 0.3) answers what the agent of tile
and the person said to each other, as the agent keeps it in its session file (its manifest's
session.transcript maps the file's records), and then sends the caller what is said next, as it
is written, until the call's connection goes:
{ "entries": [ … ], "cursor": 52311, "session": "<the session's id>" }with the event agent.said ([tile, entries, cursor, session]) for each later piece, never
before the answer. Each entry is one of
{ "id": "<its id>", "at": 1790000000000, "who": "person", "text": "<what they asked>" }
{ "id": "<its id>", "at": 1790000000000, "who": "agent", "text": "<what it said, in markdown>" }
{ "id": "<its id>", "at": 1790000000000, "who": "agent", "tool": { "id": "<the use>", "name": "Edit", "about": "src/nav.ts" } }
{ "id": "<its id>", "at": 1790000000000, "who": "agent", "tool": { "id": "<the use>", "name": "AskUserQuestion", "asks": [{ "question": "Which color?", "options": ["Red", "Blue"] }] } }
{ "id": "<its id>", "at": 1790000000000, "who": "tool", "result": { "of": "<the use>", "text": "<what it gave back>", "error": true } }
{ "id": "<its id>", "at": 1790000000000, "who": "program", "notice": { "text": "Helper finished: Tidy the docs", "quiet": true, "detail": "<what it says more>" } }- The device reads them from the file as the agent's manifest maps its records
(
session.transcript: which records say what, and in which fields; the agent providers guide has the rules). It knows no agent's format of its own.idis the record's, with/and the item's index after it for one read from a list of several items;atits time, in ms since the epoch; a tool'saboutat most 120 characters, its first line; a tool'sasks(0.7) the questions it asks the person, asneeds.mdgives them; what a tool gave back cut to 2,000 characters,erroronly when true (left out otherwise). A line that is not a record, and a record or item no rule reads, say nothing. - A
notice(0.38) is a line the agent's own program wrote into its file as if the person had said it, in the person's words: a background task finishing, a summary of what came before. Its manifest says which (session.transcript.notices), by the record and the whole of its text, so the person's own words that mention such a thing stay theirs.textat most 160 characters, one line;quietonly when true, for one that should barely register;detailwhat it says more once opened, at most 4,000 characters, left out when nothing. A reader that does not knowprogramleaves it out. Who shows a conversation folds a run of notices into one line. cursoris how far into the file the entries go (in bytes, at the end of a line), andsessionthe session whose file it is: given back, they answer only what comes after the cursor, as after a reconnect. Without them, or for a session the agent keeps no more, it answers the last 200 entries of the last 1 MiB of its file now, andbefore(0.39), the byte where the line of the first of them begins; 0 when nothing was said earlier.agent.conversationBefore(tile, session, before)(0.39) answers{entries, before}: up to 200 entries just before that byte, read back until it holds 50 or 4 MiB was read, and on past that while it holds none, at most 16 MiB (a longer line is passed over); and where the line of the first of them begins, to ask from next. A tool use it gave may be unfolded withagent.tool, with what it gave back when that is within 1 MiB of its page. It isNOT_FOUNDonce the agent is in another session.- The session is the one last recorded for the agent's tile (by its tracker, or as it was started),
else the one its manifest would resume. When the agent begins another while it is followed (as
Claude Code's
/cleardoes), and that session's file is there, the device follows that one instead: the nextagent.saidnames it, with the last of it, as answered without a cursor, and cursors into its file. Whoever follows shows a conversation begun anew. - An agent with no session file found, or whose manifest maps no transcript, answers no entries and cursor 0, no session, and nothing more.
(0.9) agent.tool(tile, use) answers one tool use of the agent's session now, unfolded, as the
person opens its row:
{ "name": "Bash", "about": "<what it is about, whole>", "input": "<its input>",
"result": { "text": "<what it gave back, whole>", "error": true }, "truncated": true }read from the records of its session file that name use, wherever they are in it, as its
manifest maps them, input as the field the manifest's tool.input names (text as it is, else
JSON, two spaces a level); about, input and result each left out when there is none (no
result: nothing given back yet), each cut to 262,144 characters, truncated then (left out
otherwise). A use the session does not name, or an agent that keeps no conversation, is
NOT_FOUND. The cases in ../conformance/conversation.json (unfolded) decide it.
Who may
agent.startable, agent.diff, agent.conversation and agent.tool may be called by who may view the
workspace; agent.places and agent.folders (0.8), which name the person's folders, and agent.start,
agent.interrupt and agent.close by who may drive its agents (role agents); all of them by the
person's own devices, a phone among them. Each of the last three is recorded in the device's audit
log against its tile, as the device that called 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.

