How do I install swarm-tools?

Run these in Claude Code: /plugin marketplace add joelhooks/swarm-tools then /plugin install swarm@swarm-tools. Then prompt normally.

Does swarm-tools auto-invoke its skills?

Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.

Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.

Agent Orchestration

Plugin

swarm-tools

Multi-agent coordination that survives context death. Break big tasks into small ones. Spawn agents to work in parallel. Learn from what works. swarmtools.ai · Documentation

FLOW.md

joelhooks@joelhooks

GitHub

Plugin Signal81/100Strong

maintained95

capable61

documented100

adopted61

Install on Claude Code

> /plugin marketplace add joelhooks/swarm-tools
> /plugin install swarm@swarm-tools

Stats

TypeScript Bash SQL SQLite Git

+6 tags

GitHub Anthropic OpenAI MCP Slack Bun

730

Stars

Forks

Active

Maintenance

TypeScript

Language

18d ago

Last commit

8mo ago

Created

Repo: joelhooks/swarm-tools

In this plugin

6 commands 6 skills 3 agents 1 MCP

See everything inside

What's inside

Badges

README

Read on GitHub

Swarm

 ███████╗██╗    ██╗ █████╗ ██████╗ ███╗   ███╗
 ██╔════╝██║    ██║██╔══██╗██╔══██╗████╗ ████║
 ███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
 ╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
 ███████║╚███╔███╔╝██║  ██║██║  ██║██║ ╚═╝ ██║
 ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝

Multi-agent coordination that survives context death.

Break big tasks into small ones. Spawn agents to work in parallel. Learn from what works.

swarmtools.ai · Documentation

Installation

OpenCode

npm install -g opencode-swarm-plugin
swarm setup

Done. Use /swarm "your task" in any OpenCode session.

Claude Code

Step 1: Install the CLI globally (required):

npm install -g opencode-swarm-plugin

Step 2: Add the marketplace in Claude Code:

/plugin
→ Manage marketplaces
→ Add marketplace
→ Enter: joelhooks/swarm-tools

Step 3: Install the plugin:

/plugin
→ Manage plugins
→ swarm-tools
→ swarm
→ Install

The MCP server starts automatically. Use /swarm "your task" in any session.

What It Does

/swarm "Add user authentication with OAuth"

Decomposes the task into parallelizable subtasks
Creates cells in the Hive (git-backed task tracker)
Spawns workers with file reservations (no conflicts)
Coordinates via Swarm Mail (embedded event store)
Reviews each completion before approval
Learns what worked for next time

Core Concepts

Hive

Git-backed task tracking in .hive/. Survives sessions, syncs via git.

hive_create({ title: "Fix auth bug", type: "bug" })
hive_cells({ status: "in_progress" })
hive_close({ id: "cell-123", reason: "Fixed" })

Hivemind

Semantic memory with embeddings. Store learnings, search later.

hivemind_store({ information: "Auth requires idempotency keys", tags: "auth,gotcha" })
hivemind_find({ query: "auth patterns" })

Swarm Mail

Actor-model coordination between agents. File reservations, messaging, checkpoints.

swarmmail_reserve({ paths: ["src/auth/*"], exclusive: true })
swarmmail_send({ to: ["worker-b"], subject: "Need types", body: "..." })

Commands

Command	Description
`/swarm <task>`	Decompose and spawn parallel workers
`/hive`	Query and manage tasks
`/inbox`	Check messages from other agents
`/status`	Swarm coordination status
`/handoff`	End session with sync and handoff notes

CLI

swarm setup      # Configure OpenCode/Claude Code integration
swarm doctor     # Check dependencies (Ollama for embeddings)
swarm init       # Initialize hive in current project
swarm config     # Show config paths

How It Works

                         Your Task
                             │
                             ▼
                    ┌────────────────┐
                    │  COORDINATOR   │
                    │                │
                    │ 1. Query past  │
                    │    sessions    │
                    │ 2. Pick strat  │
                    │ 3. Decompose   │
                    └────────────────┘
                             │
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
    ┌────────────┐    ┌────────────┐    ┌────────────┐
    │  Worker A  │    │  Worker B  │    │  Worker C  │
    │            │    │            │    │            │
    │ 🔒 files   │───▶│ 🔒 files   │    │ 🔒 files   │
    └────────────┘    └────────────┘    └────────────┘
           │                 │                 │
           └─────────────────┼─────────────────┘
                             ▼
                    ┌────────────────┐
                    │   LEARNING     │
                    │                │
                    │ Record outcome │
                    │ Update weights │
                    └────────────────┘

Architecture

Everything runs locally. No external servers.

libSQL - Embedded SQLite for event sourcing
Hive - Git-backed .hive/ directory for tasks
Hivemind - Semantic memory with Ollama embeddings (falls back to FTS)
Swarm Mail - DurableMailbox, DurableLock, DurableDeferred primitives

Event Sourcing

All state is an append-only event log:

agent_registered → Agent joins swarm
message_sent     → Agent-to-agent communication
file_reserved    → Exclusive lock acquired
file_released    → Lock released
checkpoint       → Progress snapshot
outcome          → Completion result

Learning System

Every completion records duration, errors, files touched, success.

Patterns mature: candidate → established → proven
Anti-patterns auto-generate when failure rate > 60%
Confidence decays over 90 days unless revalidated

Dependencies

Required	Optional
Bun	Ollama - local embeddings

Run swarm doctor to check status.

Embedding Model Configuration

Configure the embedding model via environment variables:

export OLLAMA_MODEL=nomic-embed-text  # Default: mxbai-embed-large
export OLLAMA_HOST=http://localhost:11434  # Default

Supported models: mxbai-embed-large (1024d), nomic-embed-text (768d), all-minilm (384d), snowflake-arctic-embed (1024d). See swarm-mail docs for details.

Development

bun install
bun turbo build
bun turbo test

Credits

MCP Agent Mail - inspiration for multi-agent coordination
Electric SQL - durable streams patterns
Superpowers - verification patterns

MIT

File tree

joelhooks/swarm-toolsView on GitHub

.changeset/
  config.json
  fix-mcp-array-coercion.md
  fix-memory-database-path.md
  fix-memory-hooks-flooding.md
  README.md
.claude/
.claude-plugin/
  marketplace.json
  .worker-tracking/
    1330404e/
      hivemind_find.marker
      hivemind_store.marker
      skills_use.marker
      swarmmail_init.marker
    82779958/
      hivemind_find.marker
      hivemind_store.marker
      swarmmail_init.marker
    9d4e31b7/
      hivemind_find.marker
      hivemind_store.marker
      skills_use.marker
      swarmmail_init.marker
    c1b0eb57/
      hivemind_find.marker
      hivemind_store.marker
      swarmmail_init.marker
    d4732745/
      hivemind_find.marker
      hivemind_store.marker
      skills_use.marker
      swarmmail_init.marker
    d67e1204/
      hivemind_find.marker
      hivemind_store.marker
      skills_use.marker
      swarmmail_init.marker
  skills/
    release/
      SKILL.md
.gitattributes
.github/
  CODEOWNERS
  dependabot.yml
  VOUCHED.td
  workflows/
    ci.yml
    codeql.yml
    dependency-review.yml
    eval-gate.yml
    opencode.yml
    publish.yml
    vouch-check-pr.yml
    vouch-manage-by-issue.yml
.gitignore
.hive/
  .gitignore
  .local_version
  analysis/
    agentic-flywheel-analysis.md
    cli-refactor-research.md
    context-graph-architecture.md
    coordinator-audit.md
    coordinator-driven-retry-adr.md
    coordinator-prompt-eval-research.md
    data-quality-audit.md
    database-path-audit.md
    eval-analysis.md
    eval-o11y-rundown-sop.md
    event-sourced-beads-feasibility.md
    feature-discovery.md
    full-observability-gap-analysis.md
    git-sync-distributed-coordination.md
    global-db-analysis.md
    hive-cell-visualizer.md
    improvement-roadmap.md
    learning-system.md
    llm-powered-compaction.md
    observability-developer-debugging.md
    observability-post-hoc-analysis.md
    observability-runtime-visibility.md
    performance-insights.md
    rejection-patterns.md
    skill-architecture-meta-skills.md
    stray-database-audit.md
    swarm-db-analysis.md
    system-health.md
    worker-efficiency.md
  config.yaml
  issues.jsonl
  memories.jsonl
  metadata.json
  README.md
.opencode/
  agents/
    adversary.md
  skill/
    gh-issue-triage/
      scripts/
        get-contributor.ts
        issue-summary.ts
      SKILL.md
    pr-triage/
      references/
        gh-api-patterns.md
      scripts/
        pr-comments.test.ts
        pr-comments.ts
      SKILL.md
    publish-package-cicd/
      references/
        changeset-config.json
        publish-script.ts
        publish-workflow.yml
      SKILL.md
    tdd/
      SKILL.md
.turbo/
  cache/
    0e77f87e34f54b4d-meta.json
    0e77f87e34f54b4d.tar.zst
    1235eeaca60f61f2-meta.json
    1235eeaca60f61f2.tar.zst
    894f236d25d72a4d-meta.json
    894f236d25d72a4d.tar.zst
    9702a1972efdf18f-meta.json
    9702a1972efdf18f.tar.zst
    ace1a5dc8db33216-meta.json
    ace1a5dc8db33216.tar.zst
    eb70accb21535826-meta.json
    eb70accb21535826.tar.zst
    f29f52c0e71b0b20-meta.json
    f29f52c0e71b0b20.tar.zst
AGENTS.md
apps/
  web/
    .gitignore
    app/
      api/
        search/
          route.ts
      docs/
        [[...slug]]/
          page.tsx
        layout.tsx
      globals.css
      icon.tsx
      layout.tsx
      llms-full.txt/
        route.ts
      llms.txt/
        route.ts
      opengraph-image.tsx
      page.tsx
      sitemap.ts
    biome.json
    CLAUDE.md
    components/
      mdx/
        ascii-banner.tsx
        mermaid.tsx
    content/
      docs/
        archive/
          credits.mdx
          index.mdx
          meta.json
          roadmap.mdx
        concepts/
          actor-model.mdx
          event-sourcing.mdx
          index.mdx
          learning-systems.mdx
          meta.json
          patterns.mdx
        decisions/
          adr-001-monorepo.mdx
          adr-002-extraction.mdx
          adr-003-performance.mdx
          adr-004-message-queue.mdx
          adr-005-devtools.mdx
          adr-006-swarm-pty.mdx
          edr-event-sourced-beads.mdx
          index.mdx
          meta.json
        getting-started/
          index.mdx
          meta.json
          philosophy.mdx
          quickstart.mdx
        index.mdx
        meta.json
        packages/
          meta.json
          opencode-plugin/
            hive.mdx
            index.mdx
            meta.json
            skills.mdx
            swarm.mdx
          swarm-mail/
            architecture.mdx
            index.mdx
            memory.mdx
            meta.json
            primitives.mdx
    lib/
      get-llm-text.ts
      layout.shared.tsx
      source.ts
      utils.ts
    mdx-components.tsx
    next-env.d.ts
    next.config.mjs
    package.json
    postcss.config.js
    source.config.ts
    tailwind.config.ts
    tsconfig.json
BUGS-TO-FILE.md
bun.lock
CHANGELOG.md
COMPACTION-THRESHOLD-TUNING.md
CONTRIBUTING.md
docs/
  adr/
    001-async-background-workers.md
    010-cass-inhousing.md
    011-hivemind-memory-unification.md
DRIZZLE-MIGRATION-STATUS.md
FEATURE-CATALOG.md
IMPLEMENTATION_SUMMARY.md
IMPLEMENTATION-NOTES-EVENT-CAPTURES.md
package.json
packages/
  claude-code-swarm-plugin/
    .claude-plugin/
      plugin.json
    agents/
      background-worker.md
      coordinator.md
      worker.md
    bin/
      mcp-server.js
      mcp-server.test.ts
      mcp-server.ts
    CHANGELOG.md
    commands/
      handoff.md
      hive.md
      inbox.md
      status.md
      swarm.md
    hooks/
      hooks.json
    package.json
    README.md
    skills/
      always-on-guidance/
        SKILL.md
      openclaw-messaging/
        SKILL.md
      swarm-coordination/
        SKILL.md
    tsconfig.json
  opencode-swarm-plugin/
    .changeset/
      swarm-insights-data-layer.md
    .claude/
      .worker-tracking/
        d4732745/
          swarmmail_init.marker
    .hive/
      analysis/
        eval-failure-analysis-2025-12-25.md
        session-data-quality-audit.md
      eval-results.json
      issues.jsonl
      memories.jsonl
    .opencode/
      eval-history.jsonl
    .test-skills-integration-1769386960151-kksi6i/
      .opencode/
        skill/
          timeout-test/
            scripts/
              slow.sh
            SKILL.md
    .test-skills-integration-1769388314325-pgvsgn/
      .opencode/
        skill/
          timeout-test/
            scripts/
              slow.sh
            SKILL.md
    bin/
      cass.characterization.test.ts
      commands/
        doctor.test.ts
        doctor.ts
        log.test.ts
        log.ts
        queue.ts
        session.ts
        status.test.ts
        status.ts
        tree.test.ts
        tree.ts
      eval-gate.test.ts
      eval-gate.ts
      swarm-setup-consolidate.test.ts
      swarm.serve.test.ts
      swarm.test.ts
      swarm.ts
      test-setup-manual.md
    bunfig.toml
    CHANGELOG.md
    claude-plugin/
      .claude-plugin/
        plugin.json
      .lsp.json
      .mcp.json
      agents/
        background-worker.md
        coordinator.md
        worker.md
      bin/
        swarm-mcp-server.cjs
        swarm-mcp-server.ts
      commands/
        handoff.md
        hive.md
        inbox.md
        ralph.md
        status.md
        swarm.md
      hooks/
        hooks.json
      README.md
      scripts/
        copyClaudePluginRuntimeAssets.ts
      skills/
        always-on-guidance/
          SKILL.md
        ralph-supervisor/
          SKILL.md
        swarm-cli/
          SKILL.md
        swarm-coordination/
          SKILL.md
      tests/
        mcp-runtime.test.ts
    docs/
      adr/
        002-cli-modular-commands-effect.md
        memory-system-eval-strategy.md
      analysis/
      analysis-socratic-planner-pattern.md
        strategy-selection-investigation.md
        subagent-coordination-patterns.md
      claude-code-integration.md
      planning/
        ADR-001-monorepo-structure.md
        ADR-002-package-extraction.md
        ADR-003-performance-improvements.md
        ADR-004-message-queue-features.md
        ADR-005-devtools-observability.md
        ADR-007-swarm-enhancements-worktree-review.md
        ADR-008-worker-handoff-protocol.md
        ADR-009-oh-my-opencode-patterns.md
        ADR-010-cass-inhousing.md
        ROADMAP.md
      plans/
        claude-code-plugin-plan.md
      semantic-memory-cli-syntax.md
      swarm-mail-architecture.md
      testing/
        context-recovery-test.md
    evalite.config.ts
    examples/
      commands/
        swarm.md
      plugin-wrapper-template.ts
      skill/
        hive-workflow/
          SKILL.md
        skill-creator/
          SKILL.md
        swarm-coordination/
          SKILL.md
    global-skills/
      cli-builder/
        references/
          advanced-patterns.md
        SKILL.md
      learning-systems/
        SKILL.md
      queue/
        SKILL.md
... 670 more

FAQ

swarm-tools is a Claude Code plugin with 8 hand-picked skills for agent orchestration work, indexed on Flowy. Install it with the command on its page. It includes release, always-on-guidance, openclaw-messaging. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.

What is swarm-tools?: Multi-agent coordination that survives context death. Break big tasks into small ones. Spawn agents to work in parallel. Learn from what works. swarmtools.ai · Documentation
How do I install swarm-tools?: Run these in Claude Code: /plugin marketplace add joelhooks/swarm-tools then /plugin install swarm@swarm-tools. Then prompt normally.
Does swarm-tools auto-invoke its skills?: Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
Is swarm-tools free?: Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.