The serve story feed
swarm serve --dev narrates what the runtime is doing as a story feed: one line per
meaningful thing that happened — an event published, a delivery made, an agent turn finished,
a stage advanced, a decision pending — rendered for whoever is watching:
- In a terminal, lines are colored semantically (red is reserved for real failures) with a live status footer.
- Piped or
--json, the feed is NDJSON — structured lines (one JSON object per fact) an agent or script can parse. Anything a human can see in the feed, a monitoring agent can consume structurally, including notices that the feed itself is degraded — for example, when a trace follower loses its connection and stops receiving lines.
--no-feed turns it off. swarm logs --follow remains the diagnostic stream — component
internals at log level — while the feed is the narrative stream; they answer different
questions.
Commands on this page are shown with their API method names (like run.trace) so API users
can find the same data; CLI users can ignore them.
Following a run
swarm run trace prints or follows a run’s causal trace: events, deliveries, state changes, and
agent turns, in order.
--event-name, --entity-id, --delivery-status, --subscriber-type,
--since, --until, --limit):
run.trace; -f opens a run.subscribe_trace stream. To list runs, use
swarm run list.
Diagnosing why a run is stuck
swarm run status <run-id> (the run.diagnose method) interprets a run’s state and reports the
blocking layer and reason. It is the single answer to “why is this run not progressing?”
Inspecting the pieces
The flight recorder
A run’s full history is four tables joined onrun_id: events (what happened),
entity_mutations (what changed, with before and after values), agent_turns (how an agent
reasoned), and event_deliveries (what was delivered). Together they answer “what did entity
X look like when event Y fired?” without reconstructing it from current state. See
Persistence, replay, and fork.