{"id":34509981,"url":"https://github.com/joelhooks/swarm-tools","last_synced_at":"2026-02-05T23:02:39.418Z","repository":{"id":328005932,"uuid":"1112015061","full_name":"joelhooks/swarm-tools","owner":"joelhooks","description":"🐝 Multi-agent swarm coordination for OpenCode with learning capabilities, agent issue tracking, and management","archived":false,"fork":false,"pushed_at":"2026-02-01T23:25:31.000Z","size":13859,"stargazers_count":381,"open_issues_count":7,"forks_count":33,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-02-02T01:34:41.424Z","etag":null,"topics":["ai-agents","machine-learning","multi-agent","opencode","swarm"],"latest_commit_sha":null,"homepage":"https://swarmtools.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joelhooks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-08T03:01:51.000Z","updated_at":"2026-02-01T23:25:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/joelhooks/swarm-tools","commit_stats":null,"previous_names":["joelhooks/opencode-swarm-plugin"],"tags_count":150,"template":false,"template_full_name":null,"purl":"pkg:github/joelhooks/swarm-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joelhooks%2Fswarm-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joelhooks%2Fswarm-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joelhooks%2Fswarm-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joelhooks%2Fswarm-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joelhooks","download_url":"https://codeload.github.com/joelhooks/swarm-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joelhooks%2Fswarm-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29137753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T23:02:30.544Z","status":"ssl_error","status_checked_at":"2026-02-05T23:02:24.945Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","machine-learning","multi-agent","opencode","swarm"],"created_at":"2025-12-24T03:39:39.406Z","updated_at":"2026-02-05T23:02:39.401Z","avatar_url":"https://github.com/joelhooks.png","language":"TypeScript","readme":"# Swarm\n\n[![npm version](https://img.shields.io/npm/v/opencode-swarm-plugin.svg)](https://www.npmjs.com/package/opencode-swarm-plugin)\n[![Documentation](https://img.shields.io/badge/docs-swarmtools.ai-blue)](https://swarmtools.ai/docs)\n\n```\n ███████╗██╗    ██╗ █████╗ ██████╗ ███╗   ███╗\n ██╔════╝██║    ██║██╔══██╗██╔══██╗████╗ ████║\n ███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║\n ╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║\n ███████║╚███╔███╔╝██║  ██║██║  ██║██║ ╚═╝ ██║\n ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝\n```\n\n**Multi-agent coordination that survives context death.**\n\nBreak big tasks into small ones. Spawn agents to work in parallel. Learn from what works.\n\n\u003e **[swarmtools.ai](https://swarmtools.ai)** · **[Documentation](https://swarmtools.ai/docs)**\n\n---\n\n## Installation\n\n### OpenCode\n\n```bash\nnpm install -g opencode-swarm-plugin\nswarm setup\n```\n\nDone. Use `/swarm \"your task\"` in any OpenCode session.\n\n### Claude Code\n\n**Step 1:** Install the CLI globally (required):\n\n```bash\nnpm install -g opencode-swarm-plugin\n```\n\n**Step 2:** Add the marketplace in Claude Code:\n\n```\n/plugin\n→ Manage marketplaces\n→ Add marketplace\n→ Enter: joelhooks/swarm-tools\n```\n\n**Step 3:** Install the plugin:\n\n```\n/plugin\n→ Manage plugins\n→ swarm-tools\n→ swarm\n→ Install\n```\n\nThe MCP server starts automatically. Use `/swarm \"your task\"` in any session.\n\n---\n\n## What It Does\n\n```\n/swarm \"Add user authentication with OAuth\"\n```\n\n1. **Decomposes** the task into parallelizable subtasks\n2. **Creates cells** in the Hive (git-backed task tracker)\n3. **Spawns workers** with file reservations (no conflicts)\n4. **Coordinates** via Swarm Mail (embedded event store)\n5. **Reviews** each completion before approval\n6. **Learns** what worked for next time\n\n---\n\n## Core Concepts\n\n### Hive\n\nGit-backed task tracking in `.hive/`. Survives sessions, syncs via git.\n\n```\nhive_create({ title: \"Fix auth bug\", type: \"bug\" })\nhive_cells({ status: \"in_progress\" })\nhive_close({ id: \"cell-123\", reason: \"Fixed\" })\n```\n\n### Hivemind\n\nSemantic memory with embeddings. Store learnings, search later.\n\n```\nhivemind_store({ information: \"Auth requires idempotency keys\", tags: \"auth,gotcha\" })\nhivemind_find({ query: \"auth patterns\" })\n```\n\n### Swarm Mail\n\nActor-model coordination between agents. File reservations, messaging, checkpoints.\n\n```\nswarmmail_reserve({ paths: [\"src/auth/*\"], exclusive: true })\nswarmmail_send({ to: [\"worker-b\"], subject: \"Need types\", body: \"...\" })\n```\n\n---\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/swarm \u003ctask\u003e` | Decompose and spawn parallel workers |\n| `/hive` | Query and manage tasks |\n| `/inbox` | Check messages from other agents |\n| `/status` | Swarm coordination status |\n| `/handoff` | End session with sync and handoff notes |\n\n---\n\n## CLI\n\n```bash\nswarm setup      # Configure OpenCode/Claude Code integration\nswarm doctor     # Check dependencies (Ollama for embeddings)\nswarm init       # Initialize hive in current project\nswarm config     # Show config paths\n```\n\n---\n\n## How It Works\n\n```\n                         Your Task\n                             │\n                             ▼\n                    ┌────────────────┐\n                    │  COORDINATOR   │\n                    │                │\n                    │ 1. Query past  │\n                    │    sessions    │\n                    │ 2. Pick strat  │\n                    │ 3. Decompose   │\n                    └────────────────┘\n                             │\n           ┌─────────────────┼─────────────────┐\n           ▼                 ▼                 ▼\n    ┌────────────┐    ┌────────────┐    ┌────────────┐\n    │  Worker A  │    │  Worker B  │    │  Worker C  │\n    │            │    │            │    │            │\n    │ 🔒 files   │───▶│ 🔒 files   │    │ 🔒 files   │\n    └────────────┘    └────────────┘    └────────────┘\n           │                 │                 │\n           └─────────────────┼─────────────────┘\n                             ▼\n                    ┌────────────────┐\n                    │   LEARNING     │\n                    │                │\n                    │ Record outcome │\n                    │ Update weights │\n                    └────────────────┘\n```\n\n---\n\n## Architecture\n\nEverything runs locally. No external servers.\n\n- **libSQL** - Embedded SQLite for event sourcing\n- **Hive** - Git-backed `.hive/` directory for tasks\n- **Hivemind** - Semantic memory with Ollama embeddings (falls back to FTS)\n- **Swarm Mail** - DurableMailbox, DurableLock, DurableDeferred primitives\n\n### Event Sourcing\n\nAll state is an append-only event log:\n\n```\nagent_registered → Agent joins swarm\nmessage_sent     → Agent-to-agent communication\nfile_reserved    → Exclusive lock acquired\nfile_released    → Lock released\ncheckpoint       → Progress snapshot\noutcome          → Completion result\n```\n\n---\n\n## Learning System\n\nEvery completion records duration, errors, files touched, success.\n\n- **Patterns** mature: candidate → established → proven\n- **Anti-patterns** auto-generate when failure rate \u003e 60%\n- **Confidence decays** over 90 days unless revalidated\n\n---\n\n## Dependencies\n\n| Required | Optional |\n|----------|----------|\n| [Bun](https://bun.sh) | [Ollama](https://ollama.ai) - local embeddings |\n\nRun `swarm doctor` to check status.\n\n---\n\n## Development\n\n```bash\nbun install\nbun turbo build\nbun turbo test\n```\n\n---\n\n## Credits\n\n- [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) - inspiration for multi-agent coordination\n- [Electric SQL](https://electric-sql.com) - durable streams patterns\n- [Superpowers](https://github.com/obra/superpowers) - verification patterns\n\n---\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoelhooks%2Fswarm-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoelhooks%2Fswarm-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoelhooks%2Fswarm-tools/lists"}