Skip to content
swarmv0.5.3
GitHub

The bussince v0.2.0

Agents talk. You keep the thread.#

Agents that coordinate instead of working is how a fleet fails — and it used to be invisible: you had to read every terminal.

See what the fleet says to itself

swarm bus stats counts the messages, the threads and the deepest one, then draws the busiest exchanges as bars. An exchange is directed, so a pair going round in circles shows up as two long rows facing each other — 38 questions and 2 decisions is a verdict, not a statistic.

swarm bus tail -f is the traffic itself, out of the terminals; swarm bus threads lists the conversations and where each stands. The TUI marks an agent that has been talking a lot, and shows the rate beside what it is doing.

  • Who may reach whom

    Left open, the bus is the complete graph. can_send gives it the shape the fleet needs — and a refusal names where to go instead, because an agent is what reads it.

    agents:
  - name: dev-1
    # upward only
    can_send: [lead-1]
  - name: lead-1
    can_send: ["@dev", triage-1]

  • When it arrives

    defer is push without the interruption: held until the agent falls quiet. Three messages that arrived during one stretch of work become one.

    defaults:
  # follows the work
  delivery: defer

# who interrupts, who does not
delivery_by_kind:
  blocked: push
  fyi: pull

  • What a message commits you to

    A question, a request or a blocked opens a debt on whoever receives it; an answer, a decision or swarm done settles it — and the message that opens one carries the command that closes it, swarm done -thread 7. note and fyi commit nobody, so swarm send never assigns work by accident. Debts outlive the hub that carried them — an agent stuck for days is itself the reason someone restarts the fleet, and the restart used to take the explanation with it.

    bus:
  # a budget per conversation
  max_turns: 6
  # arbitrates a saturated thread
  escalate_to: triage-1

  • How much it may saysince v0.5.3

    max_turns bounds a conversation, and a conversation is all it can see: one swarm send to ten agents is one command, ten interruptions and ten fresh threads, and it costs nothing. A budget prices a message by what it interrupts, once per recipient — and the ceiling is the load-bearing half: the refill rate sets the steady state, max sets the worst hour. blocked is free and cannot be priced otherwise, because an agent that cannot go on must always be able to say so.

    bus:
  budget:
    # by kind, per recipient
    cost: {fyi: 10, question: 5}

defaults:
  # what an agent may afford
  budget: {max: 60, refill: 1m}

Owed for too long

Something owed for stalled_after while the agent is idle — both halves are needed, since an agent with nothing to do is quiet and that is normal. swarm why then says who is waiting, what was asked, since when, and the command that ends it: the agent has been compacted several times by now and no longer remembers, but the bus does.

on_stalled needs a debt — and an agent can be quiet owing nothing: it finished, it was never given anything, or the fleet has been talking in kinds that open none. on_idle takes the same rules and asks that other question, and its text is yours to write: swarm knows the agent has been quiet and knows nothing else.

swarm asks — it does not decide. on_stalled writes to the agent, or to whoever can help, and still restarts, kills and reassigns nothing: the state is a guess, and a guess is an argument for asking, not for silence. An agent waiting on a long build looks exactly like one that is stuck, so the false positive costs a question rather than an interruption.

shell
swarm bus pause "shipping, stop talking"
swarm bus status         # whether anything is held back
swarm bus threads        # the open conversations
swarm bus resume -flush  # let them through, hand over the pile

When you have lost the thread

The agents keep working and keep their terminals; only what they say to each other waits. A paused bus still records — it stops interrupting, not observing.

$SWARM_AGENT
its own name
$SWARM_ROLE
its role
$SWARM_PEERS
the other agents
$SWARM_SHARED
a directory every agent can read and write
$SWARM_ROOT
the directory holding the config — the way back from a clone
$SWARM_SOCKET
the control socket, used automatically

What the agents are told

Every agent gets swarm on its PATH, pointed at the running session. message: gives it a standing brief, typed once when it first falls quiet — a CLI still drawing its banner would swallow it.

And swarm run writes them a guide to all of this, generated from your configuration.