How Swarmie Works

Swarmie is event-driven: frontends send Op messages to core, and core emits Event messages back.

Core model

• Frontend -> core: Op (for example UserMessage, SwitchModel, Shutdown)
• Core -> frontend: Event (for example TextDelta, ToolCallStart, TurnComplete, Idle)

SwarmCore starts a background session task and relays events to subscribers (TUI, server, or headless harnesses).

Session task states

The session loop has two modes:

• Idle: waiting for operations
• Active turn: running an agentic turn and multiplexing turn output + incoming ops

While a turn is active, some ops execute immediately (Interrupt, PermissionReply, Shutdown), while others are deferred until idle.

Turn loop lifecycle

For each user message:

1. Build a TurnContext snapshot (messages, tools, mode, model/provider, limits).
2. Call provider streaming API.
3. Emit deltas (TextDelta, ThinkingDelta, tool-call start/input events).
4. Append assistant response to local message history.
5. If stop reason is tool-use, execute tools through registry, run permission checks/hooks, append tool results, and continue.
6. If end-turn condition is reached, emit TurnComplete, update context usage, and emit Idle.

Tools and permissions

Tool calls are executed through the shared tool registry. Permission-gated calls emit PermissionRequest; user responses (y/n/a/!) map to PermissionReplyDecision.

Context and compaction

Core tracks token usage and emits ContextUpdate during and after turns. Compaction can run with a separate compact model when configured.

Persistence and resume

Core records rollout/state metadata as turns complete. Sessions can be resumed from persisted records via swarmie resume or server APIs.

Modes, thinking, and hooks

• Mode is included in prompt assembly and can be switched at runtime.
• Thinking level is part of request shaping.
• Hooks can fire across lifecycle events (for example prompt submit, tool phases, config changes).