Agent Skills

always-on-guidance

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

Installation
CLI
npx skills add https://github.com/joelhooks/swarm-tools --skill always-on-guidance

Install this skill with the CLI and start using the SKILL.md workflow in your workspace.

Last updated 4/21/2026

Swarm

npm version
Documentation

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

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"
  1. Decomposes the task into parallelizable subtasks
  2. Creates cells in the Hive (git-backed task tracker)
  3. Spawns workers with file reservations (no conflicts)
  4. Coordinates via Swarm Mail (embedded event store)
  5. Reviews each completion before approval
  6. 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

MIT