DOCSEARCHbyAlgolia
Submit Docs

swarm-tools

repository·main·Indexed 20 days ago

https://github.com/joelhooks/swarm-tools

A multi-agent coordination framework and Claude Code plugin designed to decompose large tasks into parallelizable subtasks. It features Hive for persistent task tracking, Hivemind for semantic memory with embeddings, and Swarm Mail for actor-model coordination and file reservations. The system utilizes a hierarchical architecture consisting of Coordinators, Workers, and Researchers to manage complex workflows via an MCP server and a global CLI (opencode-swarm-plugin).

Tokens
280.7K
Snippets
738
Records
1.1K
Agent score
71%

What's inside swarm-tools

  1. Overview of Swarm Tools capabilities

    main

    Swarm Tools is a framework for multi-agent AI coordination. It provides the following primitives to enable multiple agents to work together on complex tasks:

    • Task Decomposition: Breaking large tasks into parallelizable subtasks.
    • File Reservations: A mechanism to prevent edit conflicts when multiple agents are working concurrently.
    • Progress Tracking: Monitoring the status and completion of the swarm.
    • Learning: Improving task decomposition strategies based on previous outcomes.

  2. Overview of Swarm Mail Architecture

    main

    Swarm Mail is an embedded, event-sourced messaging system designed for multi-agent coordination. It is built using Durable Streams primitives and Effect-TS, providing actor-model communication without requiring external server dependencies like Redis, Kafka, or NATS.

    Core Use Cases

    • Coordinate file access: Prevent edit conflicts using reservations.
    • Exchange messages: Enable asynchronous communication for status updates, blockers, and handoffs.
    • Request/response: Implement synchronous-style RPC for data queries.
    • Resumability: Use positioned consumption with checkpointing to resume after crashes.
    • Auditing: Maintain a full event history of all agent actions for debugging and learning.

    Key Characteristics

    • Local-first: No external servers or network dependencies; uses PGLite (embedded Postgres).
    • Event-sourced: Provides a full audit trail.
    • Resumable: Uses checkpointed cursors for exactly-once processing.
    • Type-safe: Leverages Effect-TS for full type inference.
    • Actor-model: Supports mailboxes, envelopes, and distributed promises.
    • File safety: Uses CAS-based locks for mutual exclusion.

  3. Overview of swarm-mail

    main

    swarm-mail is a TypeScript library providing event sourcing and actor-model primitives designed for multi-agent coordination. It follows a local-first approach using libSQL (embedded SQLite) and Drizzle ORM, requiring no external servers.

    The library is organized into several key functional areas:

    • Event Store: An append-only log that automatically updates projections for agents, messages, and file reservations.
    • Actor Primitives: Durable primitives built on Effect-TS, including DurableMailbox, DurableLock, DurableCursor, and DurableDeferred.
    • Hive: A Git-synced work item tracker for managing cells, epics, and dependencies.
    • Semantic Memory: Persistent agent learning using vector embeddings via Ollama and native sqlite-vec support in libSQL.
    • Coordination: Includes HiveAdapter for work item tracking and ask<Req, Res>() for RPC-style request/response patterns.

  4. Configure Always-On Guidance for Claude Plugin Agents

    main

    The always-on-guidance skill provides rule-oriented guidance for claude-plugin agents. It is used to align agent behavior, tool usage, and model-specific defaults. It is designed to replace deprecated bd/cass references with modern swarm plugin tools.

    Related skills include swarm-coordination and testing-patterns.

  5. Understand the OpenCode Plugin tool categories

    main

    The opencode-swarm-plugin provides over 40 type-safe tools (validated with Zod) organized into three primary functional areas:

    • Beads Tools: Git-backed issue tracking (8 tools) used for persistent work management.
    • Swarm Tools: Task orchestration and parallel coordination (20+ tools) for managing complex agent workflows.
    • Skills Tools: A knowledge injection system (8 tools) used to provide context and patterns to agents.

  6. Understand the Scorer Implementation and Audit

    main

    The opencode-swarm-plugin uses a suite of Scorers to evaluate the performance of Swarm components (like Coordinators and Workers) during evaluations. Scorers are implemented in evals/scorers/ and are categorized into several types:

    • Primary Scorers: Core metrics defined in index.ts.
    • Coordinator Discipline Scorers: Metrics related to how a coordinator adheres to protocol (e.g., violations, spawn, review, speed).
    • Compaction Scorers: Metrics for evaluating data compaction quality.
    • Outcome Scorers: Metrics for evaluating the final results of a task.
    • Composite Scorers: Aggregated metrics that combine multiple individual scorers using weighted averages (e.g., overallDiscipline, compactionQuality).
    • LLM-as-Judge: Scorers that use an LLM (like Claude Haiku) to provide a qualitative score (0-1) based on a prompt.

  7. Summary of Swarm Mail Primitives

    main

    Swarm Mail provides four foundational, event-sourced, and resumable primitives for agent communication:

    1. DurableCursor: Resumable event stream consumption with checkpointing.
    2. DurableDeferred: Distributed promises for request/response patterns.
    3. DurableLock: CAS-based mutual exclusion for file reservations.
    4. DurableMailbox: Actor-style messaging with positioned consumption.

    All primitives are designed to be type-safe (using TypeScript and Effect-TS) and local-first (using embedded PGLite).

  8. What is the Ralph pattern and when to use it

    main

    Ralph is a supervisor/executor pattern designed for sequential, complex tasks that require human review and learning accumulation.

    In this pattern:

    • Supervisor (Claude): Responsible for planning stories, reviewing work, coordinating, and tracking progress.
    • Executor (Codex): Responsible for implementing each story within an isolated context.

    Key Benefits

    • Fresh context per iteration: The executor (Codex) starts with a clean state for each story, preventing context drift.
    • Validation gates: Work is only marked complete if specific validation commands (e.g., tests) pass.
    • Git-backed persistence: Completed work is preserved via commits.
    • Progress carryover: Learnings are accumulated in progress.txt and flow forward through iterations.

    When to use Ralph vs Swarm

    FeatureUse RalphUse Swarm
    Task TypeSequential tasksParallel independent tasks
    AutonomyNeeds human reviewFully autonomous
    ValidationComplex validationSimple test suites
    LearningLearning accumulationOne-shot execution
    ExecutorCodex as executorClaude workers

  9. What is evaluated in @swarmtools/evals?

    main

    The evaluation suite focuses on the following metrics for swarm-tools multi-agent coordination:

    • Coordinator Protocol: Verifies if the coordinator correctly spawns workers instead of performing work itself.
    • Coordinator Behavior: Ensures the LLM maintains its coordinator role after compaction.
    • Compaction Resumption: Checks the correctness of context injection following compaction.
    • Compaction Prompt Quality: Evaluates the quality of generated continuation prompts.
    • Task Decomposition: Assesses the quality of task splitting and file conflict detection.
    • Strategy Selection: Measures the accuracy of choosing the correct strategy based on task characteristics.
    • Decision Quality: Evaluates strategy selection quality and the relevance of precedents.

  10. What is ClientBuffer and how does it handle backpressure?

    main

    The ClientBuffer is a utility designed to handle backpressure for slow clients in streaming environments. It buffers incoming events when a client cannot consume them fast enough. To prevent memory exhaustion, it operates as a ring buffer: when the maxSize is reached, it automatically drops the oldest events to make room for new ones.

    Key metrics to monitor include:

    • size: Current number of buffered events.
    • droppedCount: Total number of events dropped due to buffer overflow.
    • isHealthy(): Returns whether the buffer is within its capacity limits.
    • getMetrics(): Returns detailed buffer statistics.

  11. What is the Coordinator Guard and how does it work?

    main

    The Coordinator Guard is a runtime enforcement mechanism in the opencode-swarm-plugin that prevents coordinators from performing tasks that should be delegated to workers. It is integrated into the tool.execute.before plugin hook.

    Core Logic

    The guard detects if an agent is in a coordinator context (triggered by hive_create_epic, swarm_decompose, or spawning a swarm-worker). If the agent is identified as a coordinator, the guard checks if the requested tool is forbidden. If a violation is detected, it throws a CoordinatorGuardError, which stops tool execution immediately.

    Context Detection

    Context is session-scoped. An agent is considered a coordinator when:

    1. An epic is created via hive_create_epic.
    2. Decomposition occurs via swarm_decompose.
    3. A task tool spawns a swarm-worker agent.

    Worker Safety

    Workers are never blocked. The guard uses the agentContext parameter to distinguish between roles:

    • agentContext: "coordinator": Guard checks are enforced.
    • agentContext: "worker": Guard is bypassed.
    // In tool.execute.before hook
if (isInCoordinatorContext(sessionId)) {
  const guardResult = checkCoordinatorGuard({
    agentContext: "coordinator",
    toolName,
    toolArgs: output.args,
  });

  if (guardResult.blocked && guardResult.error) {
    throw guardResult.error; // ❌ BLOCKS tool execution
  }
}