Skip to content
Back to search

swarm-tools

MarketplaceWorks with Claude CodeGitHub

🐝 Multi-agent swarm coordination for OpenCode with learning capabilities, agent issue tracking, and management

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/joelhooks/swarm-tools with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/joelhooks/swarm-tools'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/joelhooks--opencode-swarm-plugin/badge.svg)](/listings/joelhooks--opencode-swarm-plugin)

HTML

<a href="/listings/joelhooks--opencode-swarm-plugin"><img src="/api/listings/joelhooks--opencode-swarm-plugin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json Β· Manifest Β· 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "swarm-tools",
  3. "owner": {
  4. "name": "Joel Hooks"
  5. },
  6. "metadata": {
  7. "description": "Swarm Tools marketplace for Claude Code"
  8. },
  9. "plugins": [
  10. {
  11. "name": "swarm",
  12. "source": "./packages/claude-code-swarm-plugin",
  13. "description": "Multi-agent coordination for Claude Code (delegates to swarm CLI)",
  14. "version": "0.62.0",
  15. "author": {
  16. "name": "Joel Hooks"
  17. }
  18. }
  19. ]
  20. }
README.md Β· README Β· 243 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Swarm
  2. [![npm version](https://img.shields.io/npm/v/opencode-swarm-plugin.svg)](https://www.npmjs.com/package/opencode-swarm-plugin)
  3. [![Documentation](https://img.shields.io/badge/docs-swarmtools.ai-blue)](https://swarmtools.ai/docs)
  4. ```
  5. β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•— β–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ•—
  6. β–ˆβ–ˆβ•”β•β•β•β•β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ•‘
  7. β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•‘ β–ˆβ•— β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•”β–ˆβ–ˆβ–ˆβ–ˆβ•”β–ˆβ–ˆβ•‘
  8. β•šβ•β•β•β•β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•‘β•šβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘
  9. β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘β•šβ–ˆβ–ˆβ–ˆβ•”β–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘ β•šβ•β• β–ˆβ–ˆβ•‘
  10. β•šβ•β•β•β•β•β•β• β•šβ•β•β•β•šβ•β•β• β•šβ•β• β•šβ•β•β•šβ•β• β•šβ•β•β•šβ•β• β•šβ•β•
  11. ```
  12. **Multi-agent coordination that survives context death.**
  13. Break big tasks into small ones. Spawn agents to work in parallel. Learn from what works.
  14. > **[swarmtools.ai](https://swarmtools.ai)** Β· **[Documentation](https://swarmtools.ai/docs)**
  15. ---
  16. ## Installation
  17. ### OpenCode
  18. ```bash
  19. npm install -g opencode-swarm-plugin
  20. swarm setup
  21. ```
  22. Done. Use `/swarm "your task"` in any OpenCode session.
  23. ### Claude Code
  24. **Step 1:** Install the CLI globally (required):
  25. ```bash
  26. npm install -g opencode-swarm-plugin
  27. ```
  28. **Step 2:** Add the marketplace in Claude Code:
  29. ```
  30. /plugin
  31. β†’ Manage marketplaces
  32. β†’ Add marketplace
  33. β†’ Enter: joelhooks/swarm-tools
  34. ```
  35. **Step 3:** Install the plugin:
  36. ```
  37. /plugin
  38. β†’ Manage plugins
  39. β†’ swarm-tools
  40. β†’ swarm
  41. β†’ Install
  42. ```
  43. The MCP server starts automatically. Use `/swarm "your task"` in any session.
  44. ---
  45. ## What It Does
  46. ```
  47. /swarm "Add user authentication with OAuth"
  48. ```
  49. 1. **Decomposes** the task into parallelizable subtasks
  50. 2. **Creates cells** in the Hive (git-backed task tracker)
  51. 3. **Spawns workers** with file reservations (no conflicts)
  52. 4. **Coordinates** via Swarm Mail (embedded event store)
  53. 5. **Reviews** each completion before approval
  54. 6. **Learns** what worked for next time
  55. ---
  56. ## Core Concepts
  57. ### Hive
  58. Git-backed task tracking in `.hive/`. Survives sessions, syncs via git.
  59. ```
  60. hive_create({ title: "Fix auth bug", type: "bug" })
  61. hive_cells({ status: "in_progress" })
  62. hive_close({ id: "cell-123", reason: "Fixed" })
  63. ```
  64. ### Hivemind
  65. Semantic memory with embeddings. Store learnings, search later.
  66. ```
  67. hivemind_store({ information: "Auth requires idempotency keys", tags: "auth,gotcha" })
  68. hivemind_find({ query: "auth patterns" })
  69. ```
  70. ### Swarm Mail
  71. Actor-model coordination between agents. File reservations, messaging, checkpoints.
  72. ```
  73. swarmmail_reserve({ paths: ["src/auth/*"], exclusive: true })
  74. swarmmail_send({ to: ["worker-b"], subject: "Need types", body: "..." })
  75. ```
  76. ---
  77. ## Commands
  78. | Command | Description |
  79. |---------|-------------|
  80. | `/swarm <task>` | Decompose and spawn parallel workers |
  81. | `/hive` | Query and manage tasks |
  82. | `/inbox` | Check messages from other agents |
  83. | `/status` | Swarm coordination status |
  84. | `/handoff` | End session with sync and handoff notes |
  85. ---
  86. ## CLI
  87. ```bash
  88. swarm setup # Configure OpenCode/Claude Code integration
  89. swarm doctor # Check dependencies (Ollama for embeddings)
  90. swarm init # Initialize hive in current project
  91. swarm config # Show config paths
  92. ```
  93. ---
  94. ## How It Works
  95. ```
  96. Your Task
  97. β”‚
  98. β–Ό
  99. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  100. β”‚ COORDINATOR β”‚
  101. β”‚ β”‚
  102. β”‚ 1. Query past β”‚
  103. β”‚ sessions β”‚
  104. β”‚ 2. Pick strat β”‚
  105. β”‚ 3. Decompose β”‚
  106. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  107. β”‚
  108. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  109. β–Ό β–Ό β–Ό
  110. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  111. β”‚ Worker A β”‚ β”‚ Worker B β”‚ β”‚ Worker C β”‚
  112. β”‚ β”‚ β”‚ β”‚ β”‚ β”‚
  113. β”‚ πŸ”’ files │───▢│ πŸ”’ files β”‚ β”‚ πŸ”’ files β”‚
  114. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  115. β”‚ β”‚ β”‚
  116. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  117. β–Ό
  118. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  119. β”‚ LEARNING β”‚
  120. β”‚ β”‚
  121. β”‚ Record outcome β”‚
  122. β”‚ Update weights β”‚
  123. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  124. ```
  125. ---
  126. ## Architecture
  127. Everything runs locally. No external servers.
  128. - **libSQL** - Embedded SQLite for event sourcing
  129. - **Hive** - Git-backed `.hive/` directory for tasks
  130. - **Hivemind** - Semantic memory with Ollama embeddings (falls back to FTS)
  131. - **Swarm Mail** - DurableMailbox, DurableLock, DurableDeferred primitives
  132. ### Event Sourcing
  133. All state is an append-only event log:
  134. ```
  135. agent_registered β†’ Agent joins swarm
  136. message_sent β†’ Agent-to-agent communication
  137. file_reserved β†’ Exclusive lock acquired
  138. file_released β†’ Lock released
  139. checkpoint β†’ Progress snapshot
  140. outcome β†’ Completion result
  141. ```
  142. ---
  143. ## Learning System
  144. Every completion records duration, errors, files touched, success.
  145. - **Patterns** mature: candidate β†’ established β†’ proven
  146. - **Anti-patterns** auto-generate when failure rate > 60%
  147. - **Confidence decays** over 90 days unless revalidated
  148. ---
  149. ## Dependencies
  150. | Required | Optional |
  151. |----------|----------|
  152. | [Bun](https://bun.sh) | [Ollama](https://ollama.ai) - local embeddings |
  153. Run `swarm doctor` to check status.
  154. ### Embedding Model Configuration
  155. Configure the embedding model via environment variables:
  156. ```bash
  157. export OLLAMA_MODEL=nomic-embed-text # Default: mxbai-embed-large
  158. export OLLAMA_HOST=http://localhost:11434 # Default
  159. ```
  160. Supported models: `mxbai-embed-large` (1024d), `nomic-embed-text` (768d), `all-minilm` (384d), `snowflake-arctic-embed` (1024d). See [swarm-mail docs](packages/swarm-mail/README.md#configuring-the-embedding-model) for details.
  161. ---
  162. ## Development
  163. ```bash
  164. bun install
  165. bun turbo build
  166. bun turbo test
  167. ```
  168. ---
  169. ## Credits
  170. - [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) - inspiration for multi-agent coordination
  171. - [Electric SQL](https://electric-sql.com) - durable streams patterns
  172. - [Superpowers](https://github.com/obra/superpowers) - verification patterns
  173. ---
  174. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.