Home

tinyhivemind

Group chats for agents.

One agent answering one message is a solved problem. What is not solved is a room: several agents sharing one transcript, reading each other correctly, taking turns without stampeding, and stopping for a reason somebody can name afterwards. That is what this library is.

It is a Rust workspace of three crates, with no storage, no HTTP, and no async runtime. Your host owns the log. tinyhivemind answers questions about it.

Where to go

If you want to know what it is, read Architecture. If you want to wire it into something, start at Quick start and then Host integration. If you are here because somebody claimed a room of agents beats one agent, go straight to Benchmarks, which includes the control most such claims are missing.

The four questions the algebra answers

Who is here, what a desk is and who sits on it, who @this refers to, and what one participant sees of a transcript several participants wrote. Each answer is a fold over data you already hold. There is no IO anywhere in it.

• Desks and rosters
• Mentions
• Transcript projection
• Responder ladder

The part that converges

A shared desk on its own cannot reach a decision. tinyhivemind-hive adds a protocol for that. Agents deposit typed markers in the transcript, support accumulates, an objection silences an advocate, and the episode ends as converged, deadlocked, exhausted, or idle. It is opt-in, pure, and it never authorizes more than one speaker at a time.

• Hive episodes
• Trace grammar
• Episode policy

The numbers, briefly

Five simulated agents choosing between four options, 5000 seeded rooms:

arm       turns/ep   decided %   correct %       ns/step
ladder        1.00       100.0        57.6          1109
vote         15.00       100.0        78.5             0
hive          6.16        89.7        73.3          2231
hive+         6.75        99.4        82.1          2278

A tuned deliberation is right 82.1% of the time in under seven turns. An independent vote given the whole fifteen-turn budget reaches 78.5%. One responder answering alone, which is how most systems behave today, reaches 57.6%. The state machine itself costs about 2.3 microseconds per step.

Benchmarks has the tables behind that, the two bounds on the quorum threshold, what happens without the blind opening round, and a section on what none of it shows.

One rule worth stating up front

One message triggers one turn. @everyone resolves to a list named in that turn's context, not to a turn per member. No type in this library can carry two authorized speakers, so the rule holds by construction rather than by discipline. See ADR 0002.