Swarmscope
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SWARMSCOPE_PORT | No | Override the viewer/HTTP port (default 4319). | |
| SWARMSCOPE_NO_UI | No | Set to 1 to run stdio only, without serving the viewer/HTTP endpoint. | |
| SWARMSCOPE_RETENTION_DAYS | No | Number of days events are kept (default 7). |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Swarmscope is a local map of your AI agents and the messages, handoffs, reviews, and tool calls between them. Call report_event when one agent talks to another. Call get_network for agents and edges. Call list_events to page the log. Everything stays on this machine. Labels are short and neutral: no URLs, emails, secrets, or message text. Sending the same event_id again is a no-op.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| report_eventA | Record one event from an agent: a message, handoff, review, file write, action, alert, heartbeat, or a tool call (set tool). from and to are lowercase slugs you choose (for example planner, researcher, coder). to is required for message, handoff, and review. label is a short neutral gist, 60 characters or fewer. Set test=true for traffic you do not want in network totals. The same event_id is stored once. |
| get_networkA | Agents on this machine and the edges between them. Each edge is {from, to, kind, count, first_ts, last_ts}, counted over the retention window. Test events are left out. At most 200 edges, newest first. |
| list_eventsA | Events after a sequence number, oldest first (default 50, max 200). Page with since set to next_since. Filter with kind, from, and to. Test events are skipped unless include_test is true. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: report_event writes events, list_events reads raw events with pagination/filters, and get_network reads aggregated agent-edge topology. The descriptions make the boundary between raw events and aggregated network data explicit, so misselection is unlikely.
All three tools follow a consistent verb_noun snake_case pattern: get_network, list_events, report_event. No mixed conventions or vague verbs are present.
Three tools cover the minimal complete surface for this domain: ingest, list, and network view. Each tool earns its place, and the small set is easy to scan without redundancy.
The core lifecycle is covered (write events, read events, view derived network), but there are minor gaps: no direct event-by-id lookup, no pagination for get_network beyond the 200-edge cap, and no option to include test traffic in network views. Agents can work around most of these using list_events filters, but some dead ends remain.