Coordinate the work
Task manifests carry dependencies. Ready work can be dispatched into separate worktrees, with worker identity, phase state, retries, and completion tracked by the coordinator.
Orchestration source ↗Type a section name and press Enter. Use “help” for the list.
Figures: softened for dark viewingDisplay only; image files are unchanged.
Project record · Reviewed October 9, 2026
agent-swarm
Coordinating agents and inspecting their work
Current stateImplemented tool routing, worker coordination, workflow enforcement, and observability inside Claude Code
Approach
I built agent-swarm to make delegated software development into a process I could direct, inspect, and improve. That involves deciding how work is divided, giving workers the right context and tools, coordinating their changes, and following the result through review.
The router is the center of that design. It brings tool access, caller identity, workflow state, response handling, and telemetry into one path. The same infrastructure that governs a worker’s next action can record what that worker did.
One route for tools, coordination, and observation
The router gives the host and its workers a shared way to call tools. The controller checks the caller’s permissions, dispatches the request, and records what happened.
- 01 · Caller
Main agent or worker
A session or worker identity accompanies the request.
- 02 · Shared router
Identify → check → dispatch
Global, role, agent, and workflow-phase rules govern the tool call.
- 03 · Tool services
Files, shell, MCP backends
Native operations and configured services use the same controller.
Response → caller
Large results can return as a summary with a reference to the cached full result. Selected diagnostic commands bypass summarization.
Event → SQLite → analysis
Agent · session · workflow · phase · tool · outcome · duration · response size
Inspect how it ran
Grafana dashboards expose tool latency, errors, response summaries, and full-content retrievals. Transcript imports add usage context; a sequence miner finds recurring patterns of tool use.
Telemetry exporter ↗Assess the result
The run scorer separates recorded test outcomes, permission and workflow denials, and elapsed/tool time. Each answers a different question about the run.
Run scorer source ↗Router timing and response sizes are direct event fields. Token usage comes through separate telemetry and transcript paths; attributing shared message usage to individual tools is approximate.
Why collect the process as well as the result?
Keep useful detail within reach
A tool result can be much larger than the information a worker needs next. The router can return a shorter account while preserving the full output under a retrievable reference. This makes response handling something I can vary and measure without discarding the original evidence.
Tracing how workers used summarized responses exposed a cost: they sometimes immediately fetched the full output, paying for an extra response and call. The code now uses a larger summary threshold and exempts selected diagnostic commands. Full-content retrieval rates, retained detail, task completion, and latency can help determine which outputs benefit from summarization.
Where it stands
The code includes an MCP router and backend manager, layered permissions, workflow transitions and checkpoints, dependency-aware task dispatch, separate worktrees, retries, and response caching. The host executes the agents; agent-swarm supplies coordination and the shared tool path around them.
A worker’s workflow describes how work returns for correction as well as how it advances: write tests, implement, test, review, and return to implementation when needed. The controller checks phase transitions and forward checkpoints, then updates the permissions of bound workers. The host and workflow code still drive the process and provide its evidence.
Telemetry joins this process to inspectable records: controller events go to SQLite, transcript imports add session activity, and the companion OpenTelemetry stack supplies dashboards and recurring tool-sequence analysis. Those sequences help identify repeated work that might deserve a better tool or workflow. Session startup also consumes continuity’s project brief while memory, continuity, and experiment retain their own responsibilities. Mutable telemetry data lives outside the versioned plugin installation so an update does not create a separate history.
What the work has shown
Results from one retained batch
Five programming tasks were assigned to parallel workers.
| Assignment | Recorded passing tests | Commits |
|---|---|---|
| Skip list | 27 / 27 | 4 |
| Automatic differentiation | 68 / 68 | 7 |
| Compiler and virtual machine | 68 / 68 | 8 |
| Memory allocators | 31 / 31 | 8 |
| Vector clocks | 38 / 38 | 7 |
232 / 232 tests · 34 commits · 76m 50s
The workers wrote the tests during implementation. The record captures completed work and revisions; measuring a speed advantage would require a matched single-agent comparison.
Five programming assignments
I tested the workflows through many rounds of programming assignments, deleting the generated implementations between attempts. At first I kept earlier solutions on branches, and the agents found and reused them. After I switched to worktrees, they began picking up solutions from the worktrees themselves. I had to revise what the agents could access as well as what they were asked to do.
One retained batch covered a skip list, automatic differentiation, a compiler and virtual machine, memory allocators, and vector clocks. Revisions included edge-case fixes and replacing a quadratic ordering routine with a topological sort.
Permissions follow the worker and its current phase
A standalone implementation worker receives its own iterate workflow instance, bound to the identity attached to its tool calls. The permission check can therefore use that worker’s current phase, and normal completion removes the instance. Parallel workers can follow the same process while keeping separate phase state.
A dispatch investigation made the need for this connection concrete: the briefing told a worker to follow iterate, but the permission system only knew its role. The intended phase restrictions never applied. Binding the worker before its first routed call connected the two.
Telemetry connects each call to the work it belonged to
The event record joins a tool call to its agent, session, workflow, and phase, together with its outcome and duration. That supports questions such as where a run spent its time, which operations were blocked, and whether summaries led to full-content retrievals. The run scorer then keeps test outcomes, workflow denials, and time separately inspectable.
Checking telemetry against actual tool outcomes exposed errors in the measurements. Returned tool errors and shell timeouts had been counted as successes, while rounding left 10,934 of 17,075 historical rows with zero duration. The fixes classify returned errors and retain fractional milliseconds. A separate importer fix lets the recorded session continue growing as new calls arrive.
Artifacts and records
Coordination and tool routing
The agent-swarm source, including the router, workflows, dispatch, and response handling.
Telemetry stack
The exporter, sequence miner, and dashboards for inspecting agent activity.
What remains open
- Compare the workflow with a single-agent baseline on the same assignments, holding the model and access to prior solutions fixed and including review and integration time.
- Use full-content retrievals and task outcomes to choose where response summarization helps.
- Exercise worker binding, checkpoint re-entry, and cleanup through retries and interrupted runs, where a normal completion path is insufficient.