Many agents.One record.
hypswarm runs one agent or a swarm of them on a research or building task, with a HypGraph record as the only shared state. The record schedules the work, accepts it against predicates it checks itself, stops what a fallen premise made pointless, and writes the report. Models are called to do work and to judge exceptions — nothing else.
Take a seat
A seat is a name in the record. Hold it over MCP from Claude Code, Cursor or any client: the scheduler
issues you orders, the record tells you when each one is done, and it holds you to the same rules as
every other seat. Machine-readable: /llms.txt.
hypgraph --db study.hypgraph --as nicolas mcp # my_work → do it → return_workHow a seat works
Run a swarm
One task, a few seats, a budget. The scheduler makes no model calls; workers hold no state; the record is the audit log and it verifies by hash. Any OpenAI-compatible endpoint or Anthropic as the model; workers in one process or against a record server.
pip install hypswarm hypswarm run --task task.toml --seats seats.toml --record study.hypgraphSet it up
What a run looks like when nobody has to coordinate.
Four questions about an eval, three workers, a critic, a lead. The scheduler issues an order per open question to whichever seat fits, the workers write runs, results and claims into the record, the record accepts each order the moment its predicates are met, a critic's review settles each question, and the lead is called once: to write the interpretation under the facts. This trace is from a real run on a suite instance (the harmony study's dry-run seed, not a study seed).
- every order is a node; acceptance is a decision based on the evidence that met it
- a worker's reply after each write says whether its order is done — so it returns
- claims are checked as they're written; the report is linted against the record before it's accepted
dispatch T1 → analyst Q1 What is A's accuracy? dispatch T2 → stats Q3 Is A significantly better than B? dispatch T3 → engineer Q4 In which subset is A's advantage largest? returned T2 stats · 6 calls · returned itself settled T2 → D1 claim_made: CL2 dispatch T4 → critic review CL2 returned T1 analyst · 8 calls settled T1 → D2 claim_made: CL1 dispatch T5 → stats Q2 What is B's accuracy? returned T4 critic · 6 calls settled T4 → D3 reviewed: RV1 … 8 orders, 0 reworks, 0 escalations, lead: 4 calls (the report) BOARD Q1 SETTLED · Q2 SETTLED · Q3 SETTLED · Q4 SETTLED — 4 of 4 report accepted (checked against the record)
One program, from a solo scientist to a swarm.
A seat is a declared capability bound to an author name in the record. Prompts stay short; the work order carries the task. A solo scientist is one worker seat. A swarm is several, pulling in parallel under the record's leases, which is what keeps two of them off the same work.
worker
Takes orders from the board; writes runs, results and claims;
returns. Declares what it takes so the scheduler can match it to work.
reviewer
Takes review orders. Named as a reviewer on the investigation, so its verdicts count — never on its own author's work; the record refuses that.
lead
Called only at exceptions — an order stuck after two reworks, a contested claim, an empty frontier with questions open — and for the report's interpretation.
instrument
Not a model. A job runner (CI, a lab) that files runs the record marks as lab-recorded, so "the tests pass" is its number, not the agent's.
external
No model: a person or another agent holds the name over MCP. The scheduler issues it orders like any seat and waits. If the lease runs out, the record returns the order on its behalf.
operator
A person, reached through the record: approves budgets, answers escalations, resolves objections. Never through chat state.
Coordination that isn't a prompt.
No model calls
Issue from the question board, settle met orders, rework the rest twice, cancel what became moot, bring the lead in only at exceptions. All of it is code over the record's derived state.
No state
A worker's context is its order and its own turns. It can be killed; the lease expires and another takes the order. Every reply says whether it's done.
Can't be flattered
HypGraph's checks run on every write: numbers bound to results, no "never" without the count, no "significantly" without the test, and the record binds the numbers it already holds before it refuses anything.
A rule, not a hope
Calls and dollars, per run and per order, enforced by the scheduler and shown to every seat in every reply.
You didn't write it
Orders are task nodes, acceptance is a decision, the run files its own provenance. The record is the log, and it verifies by hash.
The world can interrupt
A file declared corrupt withdraws its artifact, registers the fix, and reaches every order issued from then on. Orders resting on the fallen premise are cancelled, and nothing else is.
Hold a seat over MCP.
The HypGraph MCP server is the whole interface. my_work shows your open orders —
objective, target, premises with their standing, what's already been tried, each predicate with how to meet
it. You register runs, record results, make claims; every reply tells you whether the order is done; you
return it. The record can't tell a person from an agent except by name.
my_work. Do what the order
says, from the files, with the tools you have. Write what you found as runs, results and claims — a claim's
numbers must come from a result, and a refusal tells you the honest version. When the reply says every
predicate is met, call return_work with a note of at most 120 words. Don't work past done.[[seats]] name = "nicolas" role = "worker" external = true
pip install "hypgraph[mcp]" claude mcp add hypgraph -- hypgraph --db study.hypgraph --as nicolas mcp # then, in the session: my_work
A task, some seats, a budget.
The core depends on hypgraph and httpx. The OpenAI-compatible adapter
covers DeepInfra, OpenAI, NVIDIA NIM, vLLM, Ollama and most gateways; hypswarm[anthropic] adds
the Messages API. Any object with async complete(messages, tools) -> Reply is a model.
Workers can share one process or talk to a record served by hypgraph serve --writable
— one record server, stateless workers on other processes or machines, and the file still verifies.
from hypswarm import Task, Seat, Budget, run
from hypswarm.providers import OpenAICompatible
task = Task(title="Does A beat B",
mission="Two models were scored on the same items (items.csv). Find out whether A beats B.",
questions=[("Q1", "What is A's accuracy?"), ("Q2", "Is A significantly better than B?")],
files={"items.csv": open("items.csv", "rb").read()})
seats = [Seat("analyst", "worker", takes=("accuracy", "counts")),
Seat("stats", "worker", takes=("significant", "test")),
Seat("critic", "reviewer"), Seat("lead", "lead")]
model = OpenAICompatible("deepseek-ai/DeepSeek-V4.1-Flash", base_url="https://api.deepinfra.com/v1/openai")
result = asyncio.run(run(task, seats, model, record="study.hypgraph", budget=Budget(max_calls=150)))
print(result.report)hypgraph --db study.hypgraph serve --writable --no-browser hypswarm run --task task.toml --seats seats.toml --record-url http://127.0.0.1:8765
Alpha, and being measured before it's described.
alpha 0.1 hypswarm grew out of the harness the HypGraph harmony study runs agent teams on, and its first measured use is as a condition in that study, preregistered before it runs. Until that study reports, this page describes what hypswarm does and not what it saves. What's built: the scheduler, workers, external seats over MCP, the record server mode, the OpenAI-compatible and Anthropic adapters, budgets, notices, and a test suite that runs every scheduler path on a scripted model in seconds. Next: the building adapter, with CI as the instrument.