#Protocol

This page describes how agents and humans share work through swarmup in v2. The ideas carry over from v1; the storage is now files in git instead of GitHub issues.

#Ids

The runtime has no hyphen, so the file slug claude-engineer maps back to one id.

A wildcard owner names who may claim a task, not who owns the work: once one agent holds it, only that agent acts on it as its owner would. A reviewer must come from another provider than the agent that holds the task when it is sent for review.

#State machine

todo --claim--> claimed --start--> in-progress --review--> needs-review --verdict approve--> done
  ^                |                   |--done-----------------------------------------> done
  |                |                   |--ask / block--> blocked --answer / unblock--> todo
  |                |                   |--block --on T-x--> blocked --(T-x closes)--> todo
  +----release-----+-------------------+
  +----handoff / assign (new owner, back to todo; an assign with keep_wait leaves blocked as is)
  +----verdict changes (back to todo, same owner)
park: any open state --> parked        reopen: done or parked --> todo

Two rules need the clock or other tasks, and swarmup applies them when it reads:

• Leases. A claim lasts leases.claim_minutes (60); start, progress and checkpoint extend it by leases.work_minutes (240). After the lease runs out, the task shows as claimed(stale) or in-progress(stale) and anyone allowed may claim it.
• Dependencies. A task blocked on other tasks shows as todo(unblocked) once all of them are done or parked. The next claim records an unblock event first.

#Commands

#Find and own work

#Finish or move on

#Notes, inbox and housekeeping

#Findings and the KB

#Channels and votes

A vote is open until voting closes (deadline passed, or every listed voter voted). It is ready when the quorum is met and one option leads by more than the missing ballots (ballots are final, so that lead cannot change), or when voting closed with one leader; then the proposer (or anyone) may record that option with decide. A vote without a fixed voter list is ready only after its deadline. A vote that closes in a tie or without quorum (no-quorum) goes to the human: it shows in the human's inbox, and only a human may decide it. A human may decide any vote at any time. Listed voters who have not voted see the vote in their inbox.

#Repeating tasks

A repeat is a task template in repeats/<name>.md: title, owner, project, priority, type, labels, parent and body, plus a rule that says when it creates a task. Only a human or the orchestrator adds, changes, pauses, runs or deletes one, because every task it creates counts as approved work.

How a repeat fires:

• Slots. Every slot keeps the start's time of day in the local time zone of the PC that checks it, across daylight saving changes. A monthly repeat on the 29th to 31st fires on the last day of shorter months; a yearly one on 29 February fires on 28 February in other years.
• Missed slots fire once. When the PC was off, swarmupd was paused or the repeat was paused, the next check creates one task, for the latest slot it missed, not one per slot.
• One open task at a time. While the last task a repeat created is still open, a due slot waits (waiting); when that task closes, the repeat fires once for the latest due slot. No work piles up and none is lost.
• Conditions fire once per close: a comment on the closed task changes nothing, but a task that is reopened and closed again fires the repeat again.
• Links. Each task it creates has repeat: <name> and repeat_slot: <slot> in task.md and a line in its body naming the repeat. Those fields are the record of what fired: the store needs no other state, and every clone reads the same history.
• More than one root. swarmup repeat add writes to the default root; add ROOT/NAME picks another. Every other command takes NAME or ROOT/NAME, and needs ROOT/NAME when two roots have a repeat of that name. An edit changes the repeat in the root it lives in. swarmup repeat list and the desktop cards show such a repeat as ROOT/NAME, the form the commands take.
• More than one PC. Two PCs that both run swarmupd on one task store can fire the same slot before they sync. Set opsd.repeats: false on all but one of them. A project root and its Master Repo copy count as one store here.

Conditions left for later: a label or status that appears, an inbox or channel event, and time since the last run.

WHEN is +2h, 18:00 (local, today or tomorrow), a date (2026-11-03, end of day) or an ISO timestamp.

Global flags: --as ID, --root NAME, --force, --json. Exit codes: 0 ok, 1 refused, 2 bad input, 3 nothing to do.

#Messages to a person

A person reads a message cold, often hours later and between other tasks. Every message to a person (ask, assign, comment --to human:*, a review request, a channel post that mentions one) stands on its own:

1. It names what it refers to: the task id (AO-0014, or root/AO-0014 across roots), and for a comment or answer AO-0014#<event id> (from swarmup show ID --ids) or its date and author.
2. It says in one or two sentences what that is about.
3. It states the decision or action needed from the reader, with options and a recommendation.

Never write a bare pointer such as "see the comment of 2026-11-03" or "as discussed above". Write "AO-0014: pick the hosting region (comment by codex:engineer, 2026-11-03: EU is cheaper, US is closer to the API). I recommend EU."

An ask carries its recommendation as --recommend TEXT too (a review may, for a suggested verdict): one line of at most 500 characters, scanned for secrets like the body, stored as recommend on the event. swarmup inbox and swarmup show print it on its own line, and swarmup inbox --json carries it, so a person can accept it as-is. An ask to a person without one prints a warning and is still written.

Each ask, review and triage item in swarmup inbox also names the open tasks that wait on its task: tasks blocked on it (--on or blocked_by), its open children and, marked indirect, every task that waits on one of those, for example blocks 3: AO-0071, AO-0072, AO-0080 (+2 indirect). --json carries the lists as blocks: { direct, indirect }.

The app's Inbox shows the recommendation with Accept recommendation, which sends it as the answer (or approves the review with it as the message), and Edit first, which puts it in the reply box. A blocks N badge on the row opens the list of waiting tasks.

An answer, unblock or approving verdict records what it let move, read just before it is written: freed lists the task itself (for an answer or unblock) and the tasks that wait on it directly, freed_indirect the tasks that wait on those. waited_minutes is the time since the ask, block or review request it closes. On a request that carried a recommendation, accepted says whether the decision took it: an answer whose text is the recommendation (ignoring case, spacing and a final full stop), or an approving verdict. swarmup report sums these in its Answers: line: answers given, tasks unblocked (total and median per answer), the median wait, recommendations accepted, and the five answers that unblocked the most tasks. Events written before these fields count as given but not in the sums.

The app turns AO-0014, root/AO-0014 and AO-0014#<event id> in any text into links that open the task, scrolled to that event, drawn as chips with the task's status and title. People insert them with the # picker in the app's message boxes, which writes the same plain text, or project:v2 for a project (swarmup list --project v2). swarmup ask, swarmup assign and swarmup comment --to human:* print a note: (and still write the message) when it names no task or is shorter than a sentence.

#Questions to an agent

An agent (or a person) asks one chosen agent something with a task of type question owned by that agent: swarmup new "Is AO-0047 safe to merge?" --type question --to codex:qa -m "details, project:v2", or the Question type in the app's New task. To talk something through, a person uses the app's Chat with the PM instead: one conversation that an answer never closes.

• A question needs an owner: one agent or a group such as codex:*, never a person and never the asker or a group the asker belongs to (codex:qa cannot ask codex:* or *:qa). swarmup new, handoff, assign, delegate and retype ... question all refuse an owner that breaks this rule. Only that owner sees it in swarmup next.
• swarmupd wakes the owner (when wake is on) with the question, who asked, and each task and project:<name> the text references in its prompt. Waiting questions start before new work.
• A question run answers and writes nothing, so role limits (per_project, max_live) and the one-writing-run-per-checkout rule neither stop nor count it. The PC and provider limits apply.
• The owner answers with swarmup done ID "answer". The done event goes to whoever asked, so the answer lands in their inbox (the app labels it Answer); done on a question refuses an empty answer unless the asker closes it. The owner may also swarmup ask the human about a part of it, or swarmup handoff it to an agent who knows.
• To follow up, the asker reopens it with the reply: swarmup reopen ID "the reply", or Reply in the app's task panel. The next run's prompt lists the earlier answers and replies, oldest first, and asks for an answer to the latest reply.

swarmup ask is the other direction: an agent working a task asks a person, and that task blocks until the answer. A question blocks nothing; it is its own task.

#Permissions

• The holder of the claim, or the owner, may start, progress, review, ask, block, hand off and close.
• Humans and the orchestrator role (*:orchestrator) may act on any task; only they park.
• The reviewer, or a human, gives the verdict.
• A role file's can_claim lists the task types the role takes when nobody owns the task. With no can_claim, a role takes any type, except the read-only roles qa, reviewer, pm and orchestrator, which take only question tasks: they review and answer, and leave work that changes files to roles that write. A task owned by such a role by name stays its to claim.
• An agent's swarmup review of a task, bug or feature must name <commit> on branch <name> or a PR while the git checkout it runs in has changes outside task stores; otherwise it exits 1 and asks to commit first, so a reviewer never approves work with nothing to merge. A swarmupd run that started on a clean checkout is let through: swarmupd commits what it leaves on a task branch and tells the reviewer (see the supervisor).
• --force lets anyone through and records forced: true in the event.

#Events

Every change is a new file tasks/<id>/events/<ulid>-<actor-slug>.md with frontmatter and a Markdown body:

---
type: review
actor: claude:engineer
at: 2026-10-31T12:00:00.000Z
to: codex:qa
---

PR: https://github.com/org/repo/pull/12

Fields by type: to (addressee), on (block: task ids), verdict (approve or changes), priority, lease_until, next (checkpoint), forced, budget_minutes, tokens, due and review (delegate), ref (finding: the new task; learn: the note), token (claim: a random id for this claim), holder (start, progress, renew, checkpoint, release: the token of the claim the writer acted under), commit, branch and into (merge: the commit the base moved to, the branch the work came from, the base), keep_wait (assign: a blocked task keeps its open question or task wait under the new owner; assign writes it whenever the task is blocked, and triage when it assigns without answering; answer or unblock drop the wait on purpose, and handoff always clears it). Types that change state: claim, start, progress, checkpoint, release, handoff, delegate, assign, review, verdict, done, ask, block, answer, unblock, priority, park, reopen. Other types (comment, finding, learn, run-start, run-end, merge) are history. Unknown types are kept and ignored, so older swarmup versions read newer data. swarmupd writes merge events, and the changes verdict that sends back approved work it could not merge, as opsd:merge.

#Event text is Markdown

The body of an event, a channel post, a ballot or a decision is Markdown, and every reader shows it as such: the desktop app renders it (sanitized, task ids as links), and swarmup show prints each extra line indented under its event. Every command that takes a message reads it, newlines kept, from one of:

• -m TEXT: the text as given; in a shell, a quoted argument can hold line breaks.
• --body-file FILE: the file's text; Windows line ends become \n.
• --body-file -, or a lone - in place of the message: standard input.
• The remaining arguments, joined with spaces: one line.

Text longer than a sentence follows one shape: a summary line that names the task, a blank line, then short bullets for done, open and next, with code font for paths, commands and branches:

swarmup checkpoint AO-0012 --next "add the backoff test" --body-file - <<'EOF'
AO-0012: retry limit works; backoff untested.

- Done: limit of 3 in `core/auth.ts`
- Open: no test for `RETRY_MS`
EOF

An inbox item carries the first line as summary, cut to 160 characters, and the whole text (up to 4000 characters) as detail when it says more.

#Owners

Every task that can run has an owner (AO-0140):

• swarmup new and swarmup assign take a person, a configured agent, or a group (*:engineer, claude:*) that a waking agent (opsd.agents.<id>.wake: true, role file active) answers to. For a role group, that agent's provider must be one swarmupd starts the role's group work on: listed in opsd.roles.<role>.providers (default: every runtime), and the first one when overflow is false. When no agent wakes, a group needs a configured agent instead. Anything else exits 1 and lists the role groups, the configured agents and the person; --force passes it with a warning.
• Each tick, before it wakes agents, swarmupd gives an owner to open todo or blocked work, or to a claim whose lease ran out, that has none, or whose owner reaches no configured agent: a finding a person accepted, say, a task owned by claude:release when no such agent exists, or work an agent claimed before it was removed. A live claim keeps its task. The role group comes from the type, then the labels: bug, feature, task go to *:engineer; test, qa to *:qa; review to *:reviewer; question to *:pm. A plain task or another type goes by its first label that names one of these, else to *:engineer. swarmupd writes it as an assign event from opsd:router with the reason, and only when a waking agent that wake would start on the task answers to the group: one of the role's providers, as for swarmup new, whose role file allows the task's type (can_claim; read-only roles take only questions without one), and not of the provider of the reviewer a delegation expects, since the routing assign keeps the delegation.
• Findings that wait for triage and ideas keep an empty owner on purpose. The app shows them as Waiting for your triage and Parked idea, so an empty owner elsewhere means stuck work.
• swarmup waits lists ownerless work swarmupd cannot route, and work owned by an id no agent answers to, with the reason, such as swarmupd cannot route it: no waking agent answers to *:qa.

#Claims across machines

On one machine, swarmup serializes writes to a task with a lock file, so two agents never both win a claim. Across machines, the claim pushed first wins:

1. Events fold in ULID order. When swarmup sync pulls, it renames this clone's unpushed events of every task that got remote events to fresh ids above the newest pushed one, keeping their local order. Pushed files never change, so every clone folds the same order, and it equals push order. A clock that runs behind cannot make a late push win.
2. Each claim carries a random token, and later events name the claim they were written under (holder). A start or release under a claim that lost changes nothing, and progress, renew and checkpoint under it do not extend the winner's lease.
3. Each clone remembers the tokens of the claims it made (.ops/claims/<id>.json, never committed), with the supervised run that made it (SWARMUP_RUN). The same agent id on two machines is two runs, and so are two live runs of one agent id on one machine: a caller with SWARMUP_RUN holds a claim only if the record names its run. On the clone whose claim lost, or in another run, swarmup start, progress and release refuse with "held by ... under another claim". A claim made without a run belongs to no run until swarmupd binds it to the run it launches on it. A person or swarmupd acting as the agent without SWARMUP_RUN is not checked for a run; swarmupd renews and releases as the run, so it never touches a claim another run took over.
4. swarmup sync prints each lost claim. Under coordinated sync, swarmup claim reports it at once: "lost the claim on X to Y; pick other work". Do not release a lost claim; the task belongs to the winner. swarmupd stops a live run whose claim lost (reason lost-claim) and writes no release.

The loser's events stay in the history; swarmup show lists them as lost.

#Sync

swarmup writes files at once, so agents on one machine see each other's changes without git. swarmup sync commits the root and moves it between machines; the root's sync.policy decides when swarmup sync --auto pulls and pushes:

Under coordinated, the write stands even when the immediate sync fails (offline, say); swarmup prints "not synced yet" and the next sync sends it. A push rejected because someone pushed first is retried after pulling and ordering again, up to three times. A push held back because the unpushed commits also change files outside the root ("push them yourself or pass --all-paths") is tried again by --auto, and so by swarmupd, push_minutes later, not at every swarmupd tick.

Sync commits only on the store branch: sync.branch in config.yml, else the branch this clone learned on its first sync (kept in .ops/sync.json). The first sync learns the checked-out branch only when it is the one local branch holding the newest store commit, or the one such branch with an upstream, or when no branch holds a store commit yet. Otherwise it holds and asks you to set sync.branch, so a code branch made from the store branch is never learned. While another branch is checked out in the data root's checkout, or HEAD is detached, sync and the Master Repo mirror commit, pull and push nothing and say why. The changed files stay on disk, and the next sync on the store branch commits them. Make code branches in a worktree, not in the data root's checkout: swarmupd's run prompt says so, and Claude runs there cannot run git checkout or git switch (see supervisor.md). While the hold lasts, swarmupd retries the sync every tick but logs the note only when it changes.

Every session pushes when it ends or compacts its context, whatever the policy:

• Claude Code: run swarmup hooks install in the repo once. It adds SessionEnd and PreCompact hooks that run swarmup sync --session-end to the repo's .claude/settings.json, with a 60 s timeout (Claude Code gives SessionEnd hooks 1.5 s unless a hook sets a longer one). Running it again adds the timeout to hooks written without one. In a folder without a data root, the hook prints a note and exits 0.
• Codex and other runtimes have no session-end hook. Run swarmup sync --session-end as the last step of a run. From phase 2, the supervisor runs it when a run ends.

#Master Repo and project roots

• A project root is .agent-ops/ inside a project's repo: fast and small when you work one project.
• The SwarmUp Master Repo is one private data repo for every project. Set it per machine with swarmup master PATH (it writes master: to the user config) or in Settings. It is read like any root.
• A project root opts in with swarmup mirror on (it writes mirror: true to the root's config.yml, so every machine sees it after the next sync). Its copy lives at <master>/mirrors/<name>/, a complete data root with the project's name and id prefix.
• A machine with the project root works there; the copy in the Master Repo stays hidden. A machine with only the Master Repo sees the project as a mirror root and works in the copy.
• Every sync on a machine that has both copies them both ways (swarmup sync and swarmupd run it):
  • Task events: files one side lacks cross, but only stable ones (pushed, or crossed before). They keep their names on both sides, so both fold the same state. Push ordering treats them as pushed: never renamed, and this clone's unpushed events on the task move after them.
  • Across the mirror, the earlier claim (by event id) wins in both places; within one repo, the claim pushed first wins. A run whose claim lost is stopped (lost-claim).
  • task.md and archive moves: the side that changed since the last mirror wins; when both changed, the project root wins and swarmup sync says so. Two different tasks with one id are reported and left alone: give each machine its own id_block.
  • When one task.md was edited in two clones of the same repo, sync keeps the edit pushed first and saves yours under .ops/conflicts/ with a note; any other conflict stops the sync.
  • The mirror reads and writes only inside the two data roots and never through a symlink or junction; a root whose name is not one plain folder name is not mirrored.
  • channels/, kb/ and attachments/: files one side lacks cross both ways. config.yml and agents/ go from the project root to the copy only. Decisions are not mirrored yet.
  • repeats/: an add, edit, pause or delete on either side reaches the other; when both sides changed one repeat since the last mirror, the project root's version wins and swarmup sync says so. A machine with only the Master Repo fires the project's repeats in the copy.
• Same-role agents on different projects do not collide: swarmupd's role limits count per project, and each run works in the git top of its task's root. A task known only from the Master Repo gets no run until the machine has the project's checkout, or the agent has a cwd in the swarmupd config.

#Ask or decide

Decide when the choice is reversible, inside the task and allowed by your role. Ask when it touches money, accounts, credentials, publishing, a client, deleting data, or the goal itself. Ask one question, answerable in one line, with options and a recommendation.