### Install and Setup OpenCode Plugin

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/packages/opencode-plugin/index.mdx

Install the plugin globally and run the setup command to prepare your environment.

```bash
npm install -g opencode-swarm-plugin@latest
swarm setup
```

--------------------------------

### Install and Setup Swarm Plugin

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/README.md

Globally install the swarm plugin using Bun and run the setup command. Note that Bun must be installed to run the CLI.

```bash
bun install -g opencode-swarm-plugin@latest
swarm setup
```

--------------------------------

### SKILL.md 'Examples' Section Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/examples/skill/skill-creator/SKILL.md

Demonstrates realistic user requests and the corresponding step-by-step process the skill will guide the user through.

```markdown
## Examples

### Example: Realistic Scenario

**User**: "Help me do X"

**Process**:
1. First step
2. Second step
3. Final step
```

--------------------------------

### Interactive Mode: User Prompt for Migration

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/IMPLEMENTATION-SUMMARY-DB-CONSOLIDATION.md

Example output of the `swarm setup` command in interactive mode, prompting the user to confirm migration of detected stray databases to the global database. The user can choose to proceed or skip.

```bash
$ swarm setup

Checking for stray databases...
Found 3 stray databases:
  - .opencode/swarm.db (390 cells, 1429 events)
  - .hive/swarm-mail.db (519 issues - legacy schema)
  - packages/plugin/.opencode/swarm.db (8103 events)

Migrate to global database (~/.config/swarm-tools/swarm.db)? [Y/n]
```

--------------------------------

### Clean Output When No Stray Databases Found

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/IMPLEMENTATION-SUMMARY-DB-CONSOLIDATION.md

Example output of the `swarm setup` command when no stray databases are detected. The output is clean and indicates that no migration is necessary.

```bash
$ swarm setup

Checking for stray databases...
  No stray databases found
```

--------------------------------

### Setup Swarm Tools

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/getting-started/quickstart.mdx

Run the setup command to configure the OpenCode plugin, initialize the hive, and handle database migrations.

```bash
swarm setup
```

--------------------------------

### Install Ollama for Semantic Memory

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/README.md

Install Ollama and start the server to enable semantic memory features. Pull a model for embedding.

```bash
brew install ollama
ollama serve &
ollama pull mxbai-embed-large
```

--------------------------------

### Install Dependencies and Build Plugin

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/claude-code-swarm-plugin/README.md

Commands to install project dependencies and build the MCP server bundle. Ensure Node.js and Bun are installed.

```bash
bun install

bun run build
```

--------------------------------

### Install Swarm Plugin from GitHub Marketplace

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/README.md

Install the swarm plugin from the GitHub marketplace using the provided commands.

```bash
/plugin marketplace add joelhooks/swarm-tools
/plugin install swarm@swarm-tools
```

--------------------------------

### Install Swarm CLI and Plugin

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/swarm-tools/README.md

Install the required swarm CLI globally and then install the swarm plugin for Clawdbot.

```bash
# Install swarm CLI (required)
npm install -g @opencode/swarm

# Install plugin
clawdbot plugins install clawdbot-swarm-plugin
```

--------------------------------

### Install and Build Project with Bun

Source: https://github.com/joelhooks/swarm-tools/blob/main/README.md

Install project dependencies and build the project using Bun and Turbo. Run these commands in the project's root directory.

```bash
bun install
bun turbo build
bun turbo test
```

--------------------------------

### Start a Session with hive_ready()

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/getting-started/quickstart.mdx

Use `hive_ready()` to initiate a new session before starting your work.

```bash
hive_ready()
```

--------------------------------

### Install opencode-swarm-plugin

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/packages/swarm-mail/memory.mdx

Install the necessary plugin for semantic memory functionality.

```bash
bun add opencode-swarm-plugin
```

--------------------------------

### Install Swarm Plugin

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/claude-code-swarm-plugin/README.md

Install the swarm plugin from the previously added swarm-tools marketplace.

```bash
claude /plugin install swarm@swarm-tools
```

--------------------------------

### Hive Session Workflow Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/packages/opencode-plugin/hive.mdx

Demonstrates a typical session workflow using Hive functions. This includes initializing the session, querying progress, starting, updating, and closing tasks, and finally synchronizing the session.

```typescript
// Session start
hive_ready()                              // What's next?
hive_query({ status: "in_progress" })     // What's mid-flight?

// Start work
hive_start({ id: "bd-123" })

// Update if needed
hive_update({
  id: "bd-123",
  description: "Updated scope to include refresh tokens"
})

// Complete
hive_close({
  id: "bd-123",
  reason: "Done: OAuth implemented with refresh"
})

// Session end (MANDATORY)
hive_sync()
```

--------------------------------

### Install Bun

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/README.md

Install Bun, a required runtime for the CLI. This command uses a script to install Bun.

```bash
curl -fsSL https://bun.sh/install | bash
```

--------------------------------

### Install and Verify opencode-swarm-plugin

Source: https://github.com/joelhooks/swarm-tools/blob/main/SWARM-TESTING-GUIDE.md

Install the swarm plugin globally and verify its installation. Ensure Ollama is running for semantic memory features.

```bash
bun add -g opencode-swarm-plugin

swarm --version

ollama serve &
ollama pull mxbai-embed-large

cd /path/to/your/project
opencode
```

--------------------------------

### Test swarm setup with stray databases

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/bin/test-setup-manual.md

Run these commands to test swarm setup when stray databases exist. This scenario requires creating a dummy database file first.

```bash
cd /tmp
mkdir test-swarm-setup-2
cd test-swarm-setup-2
mkdir -p .opencode
echo "fake" > .opencode/swarm.db
swarm setup -y
```

--------------------------------

### Install Swarm CLI

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/claude-code-swarm-plugin/README.md

Install the swarm CLI globally using either bun or npm. This is a prerequisite for using the plugin.

```bash
bun add -g opencode-swarm-plugin
```

```bash
npm install -g opencode-swarm-plugin
```

--------------------------------

### Install Swarm Tools with Bun

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/getting-started/quickstart.mdx

Install the OpenCode swarm plugin globally using Bun. Ensure you have Node.js 18+.

```bash
bun add -g opencode-swarm-plugin@latest
```

--------------------------------

### Compaction Recommendation Log Output Example (JSON)

Source: https://github.com/joelhooks/swarm-tools/blob/main/COMPACTION-THRESHOLD-TUNING.md

An example of the JSON output generated when compaction is recommended, showing the reasons and relevant counts.

```json
{
  "level": "info",
  "module": "compaction",
  "compaction_recommended": true,
  "reasons": ["3 active reservations", "2 registered agents"],
  "open_subtasks": 0,
  "active_reservations": 3,
  "registered_agents": 2,
  "msg": "compaction recommended"
}
```

--------------------------------

### Test swarm setup with no stray databases

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/bin/test-setup-manual.md

Execute these commands to set up swarm when no stray databases are present. This verifies the initial setup process.

```bash
cd /tmp
mkdir test-swarm-setup-1
cd test-swarm-setup-1
swarm setup -y
```

--------------------------------

### Install Swarm CLI for OpenCode

Source: https://github.com/joelhooks/swarm-tools/blob/main/README.md

Installs the Swarm CLI globally for use with OpenCode. After installation, use the /swarm command in any OpenCode session.

```bash
npm install -g opencode-swarm-plugin
swarm setup
```

--------------------------------

### Bun Install Command

Source: https://github.com/joelhooks/swarm-tools/blob/main/AGENTS.md

Installs all workspace dependencies for the monorepo.

```bash
# Install all workspace dependencies
bun install
```

--------------------------------

### File-Based Decomposition Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/concepts/patterns.mdx

Illustrates file-based decomposition for tasks like refactoring or migrations. The example shows a task 'Migrate from Moment.js to date-fns' broken down into subtasks, each targeting a specific file or directory.

```text
Task: "Migrate from Moment.js to date-fns"

Subtasks:
├── bd-123.1: Migrate src/utils/dates.ts
├── bd-123.2: Migrate src/components/Calendar.tsx
├── bd-123.3: Migrate src/api/scheduling.ts
└── bd-123.4: Update tests
```

--------------------------------

### Install Swarm Plugin via Marketplace

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/claude-plugin/README.md

Install the swarm plugin through the Claude Code marketplace by first adding the marketplace to your settings.

```bash
claude /plugin install swarm
```

--------------------------------

### Install Swarm Tools with npm

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/getting-started/quickstart.mdx

Install the OpenCode swarm plugin globally using npm. Ensure you have Node.js 18+.

```bash
npm install -g opencode-swarm-plugin@latest
```

--------------------------------

### CLI Integration for Swarm Setup

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/swarm-mail/src/db/CONSOLIDATION.md

Demonstrates how the `consolidateDatabases` function is integrated into the `swarm setup` command, handling user input for confirmation and logging the migration summary.

```typescript
import { consolidateDatabases } from "swarm-mail/db";

// In swarm setup command
const globalDbPath = join(homedir(), ".config", "swarm-tools", "swarm.db");
const report = await consolidateDatabases(projectPath, globalDbPath, {
  yes: argv.yes,
  interactive: !argv.yes
});

console.log(`Migrated ${report.totalRowsMigrated} rows from ${report.straysMigrated} databases`);
```

--------------------------------

### SKILL.md Description Field - Good Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/global-skills/skill-generator/references/conventions.md

Provides a well-structured example of the 'description' field in SKILL.md frontmatter, detailing functionality, use cases, and contexts.

```yaml
description: Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when working with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks.
```

--------------------------------

### Example Swarm Session Summary

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/claude-plugin/commands/swarm.md

An example of a complete ASCII art session summary, including a banner, architecture diagram, task breakdown, and statistics. This format is mandatory for all swarm completions.

```text
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                    🐝 SWARM COMPLETE 🐝                     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

    EPIC: Add User Authentication
    ══════════════════════════════

    ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
    │   OAuth     │────▶│   Session   │────▶│  Protected  │
    │   Provider  │     │   Manager   │     │   Routes    │
    └─────────────┘     └─────────────┘     └─────────────┘

    SUBTASKS
    ────────
    ├── auth-123.1 ✓ OAuth provider setup
    ├── auth-123.2 ✓ Session management
    ├── auth-123.3 ✓ Protected route middleware
    └── auth-123.4 ✓ Integration tests

    STATS
    ─────
    Files Modified:  12
    Tests Added:     24

        \   ^__^
         \  (oo)\л_______
            (__)\       )\/л
                ||----w |
                ||     ||

    moo. ship it.
```

--------------------------------

### Clean Build and Install

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/docs/planning/ADR-002-package-extraction.md

This bash script performs a clean build by removing existing 'node_modules' and 'dist' directories, then reinstalls dependencies using 'bun install'.

```bash
# Clean build
rm -rf node_modules packages/*/dist
bun install
```

--------------------------------

### Install Swarm Plugin for Claude Code

Source: https://github.com/joelhooks/swarm-tools/blob/main/README.md

Installs the Swarm plugin for Claude Code. This involves adding a marketplace, installing the plugin, and then enabling it. The MCP server starts automatically.

```bash
npm install -g opencode-swarm-plugin
```

--------------------------------

### Primitives vs. Frameworks Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/getting-started/philosophy.mdx

Illustrates the difference between a framework approach and a primitives approach to building solutions.

```text
❌ Framework approach: "Use our opinionated full-stack solution"
✓ Primitives approach: "Here's an event store. Here's a lock. Compose them."
```

--------------------------------

### Hivemind Usage Workflow Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/AGENTS.md

This bash example outlines a typical workflow using Hivemind tools: first querying for relevant learnings before starting work, then storing new learnings after solving a problem, and finally validating memories.

```bash
# 1. Before starting work - query for relevant learnings
hivemind_find({ query: "<task keywords>", limit: 5 })
```

```bash
# 2. Do the work...

# 3. After solving hard problem - store learning
hivemind_store({
  information: "<what you learned, WHY it matters>",
  tags: "<relevant,tags>"
})
```

```bash
# 4. Validate memories when you confirm they're still accurate
hivemind_validate({ id: "<memory-id>" })
```

--------------------------------

### Set up Historical Context (CASS)

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/README.md

Clone the CASS repository, install it, and periodically index new sessions to enable historical context queries.

```bash
git clone https://github.com/Dicklesworthstone/coding_agent_session_search
cd coding_agent_session_search
pip install -e .
cass index  # Run periodically to index new sessions
```

--------------------------------

### Record Message Latency with Prometheus

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/docs/planning/ADR-005-devtools-observability.md

Example of recording message delivery latency using a Prometheus Histogram. Ensure `prom-client` is installed and a registry is configured.

```typescript
import { Registry, Histogram } from 'prom-client'

const messageLatency = new Histogram({
  name: 'swarm_message_latency_seconds',
  help: 'Message delivery latency',
  buckets: [0.01, 0.05, 0.1, 0.5, 1.0, 5.0]
})

// Record latency
const start = Date.now()
await sendMessage(msg)
const latency = (Date.now() - start) / 1000
messageLatency.observe(latency)
```

--------------------------------

### SKILL.md 'Instructions' Section Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/examples/skill/skill-creator/SKILL.md

Outlines the actionable, imperative steps a user should follow when using the skill to accomplish a task.

```markdown
## Instructions

1. Read the configuration file first
2. Check for existing patterns before creating
3. Always validate output before completing
```

--------------------------------

### Find Memories for Debugging

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/packages/swarm-mail/memory.mdx

Query memory before starting complex debugging sessions to find relevant information. This example searches for 'authentication error 401'.

```typescript
semantic-memory_find({ query: "authentication error 401", limit: 5 })
```

--------------------------------

### Example References Directory Structure

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/global-skills/skill-generator/references/conventions.md

Shows how to structure documentation and reference files within a skill's 'references/' directory.

```bash
references/
├── api-reference.md
├── database-schema.md
└── advanced-workflows.md
```

--------------------------------

### Initialize Ralph Project

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/claude-plugin/commands/ralph.md

Use this command to set up a new Ralph project, creating essential configuration files like prd.json and progress.txt.

```javascript
ralph_init({ project_name: "My Project", description: "..." })
```

--------------------------------

### PR Triage Script: Get Unreplied Comments

Source: https://github.com/joelhooks/swarm-tools/blob/main/AGENTS.md

Use this command to fetch unreplied comments for a given repository and pull request number. This is the starting point for the PR triage process.

```bash
# 1. Get unreplied comments (start here)
bun run .opencode/skills/pr-triage/scripts/pr-comments.ts unreplied owner/repo 42
```

--------------------------------

### Quick Start: Build and Execute a Query

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/swarm-mail/src/analytics/README.md

Demonstrates how to build a SQL query using the QueryBuilder and execute it against a database. Ensure you provide a database adapter for execution. The result is then formatted using `formatTable`.

```typescript
import { QueryBuilder, formatTable } from "swarm-mail";

// Build a query
const query = new QueryBuilder()
  .select(["type", "COUNT(*) as count"])
  .from("events")
  .where("project_key = ?", ["my-project"])
  .groupBy("type")
  .orderBy("count", "DESC")
  .limit(10)
  .withName("event-counts")
  .withDescription("Event type counts by project")
  .build();

// Execute (you provide the database adapter)
const result = await db.query(query.sql, Object.values(query.parameters || {}));

// Format output
console.log(formatTable(result));
```

--------------------------------

### CLI Usage for Queue Management

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/global-skills/queue/SKILL.md

Examples of using the swarm CLI to manage queue operations, including submitting jobs, checking status, listing queue contents, starting workers, and cleaning up old jobs.

```bash
# Submit a job
swarm queue submit embeddings '{"text":"hello","model":"small"}' --priority 1

# Check job status
swarm queue status embeddings job-id-123

# List queue contents
swarm queue list embeddings --state waiting --limit 10
swarm queue list embeddings --state failed

# Start a worker
swarm worker embeddings --concurrency 4

# Cleanup old jobs
swarm queue cleanup embeddings --before 7d
```

--------------------------------

### Resumable Event Processing with DurableCursor

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/packages/swarm-mail/primitives.mdx

An example of setting up and running a resumable event processor using DurableCursor. It logs the starting position, processes events, and commits them. Crashes will result in resuming from the last committed position.

```typescript
import { DurableCursor } from "swarm-mail/streams/effect/cursor";
import { DurableCursorLive } from "swarm-mail/streams/effect/layers";

const program = Effect.gen(function* () {
  const cursorService = yield* DurableCursor;

  const cursor = yield* cursorService.create({
    stream: "projects/foo/events",
    checkpoint: "workers/event-processor",
    batchSize: 50,
  });

  console.log("Starting from position:", yield* cursor.getPosition());

  for await (const msg of cursor.consume()) {
    console.log("Processing event:", msg.value);

    // Simulate processing
    yield* Effect.sleep("100 millis");

    // Checkpoint position
    yield* msg.commit();
  }
});

Effect.runPromise(program.pipe(Effect.provide(DurableCursorLive)));

// If this crashes, next run starts from last committed position
```

--------------------------------

### Agent Prompt: Constraints

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/docs/analysis/subagent-coordination-patterns.md

Provides examples of constraints that can be added to agent prompts to prevent scope creep and guide the agent's actions. These constraints ensure the agent focuses on the core problem without introducing unintended changes.

```markdown
✓ "Do NOT just increase timeouts - find the real issue"
✓ "Do NOT change production code - fix tests only"
✓ "Don't refactor - minimal changes to make tests pass"
```

--------------------------------

### SKILL.md 'When to Use' Section Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/examples/skill/skill-creator/SKILL.md

Provides specific scenarios and conditions under which the skill should be triggered, aiding in its discoverability and correct invocation.

```markdown
## When to Use This Skill

- When working on X type of task
- When files matching Y pattern are involved
- When the user asks about Z topic
```

--------------------------------

### Skill Directory Structure Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/global-skills/skill-generator/references/conventions.md

Illustrates the standard directory layout for a skill, including required and optional files and subdirectories.

```bash
skill-name/
├── SKILL.md                    (required)
├── LICENSE.txt                 (optional)
├── scripts/                    (optional)
│   ├── example-script.sh
│   └── helper-tool.py
├── references/                 (optional)
│   ├── api-docs.md
│   └── detailed-guide.md
└── assets/                     (optional)
    ├── template.html
    └── logo.png
```

--------------------------------

### Get Automatic Fix Suggestions for Errors

Source: https://github.com/joelhooks/swarm-tools/blob/main/AGENTS.md

The `suggestFix` function analyzes an error and provides actionable suggestions for common Swarm-related problems. It's useful for guiding users towards resolving issues like agent initialization or resource conflicts.

```typescript
import { suggestFix } from "opencode-swarm-plugin";

try {
  await swarmmail_reserve(["src/auth.ts"]);
} catch (error) {
  const suggestion = suggestFix(error);
  if (suggestion) {
    console.log(suggestion);
  }
  throw error;
}
```

--------------------------------

### Swarm CLI Setup and Configuration

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/README.md

Commands for setting up the Swarm CLI, checking dependency health, initializing the hive, managing configuration, updating the plugin, migrating databases, and viewing version information.

```bash
swarm setup        # Interactive installer for all dependencies
swarm setup -y     # Non-interactive mode (auto-migrate stray databases)
swarm doctor       # Check dependency health (CASS, UBS, Ollama)
swarm init         # Initialize hive in current project
swarm config       # Show config file paths
swarm update       # Update swarm plugin and bundled skills
swarm migrate      # Migrate from legacy PGLite to libSQL
swarm version      # Show version info
```

--------------------------------

### Non-Interactive Mode: Automatic Migration Confirmation

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/IMPLEMENTATION-SUMMARY-DB-CONSOLIDATION.md

Example output of the `swarm setup -y` command in non-interactive mode, showing the automatic migration of stray databases without user intervention. It provides a summary of records migrated and skipped per database.

```bash
$ swarm setup -y

Checking for stray databases...
✓ Migrated 9032 records from 3 stray database(s)
  .hive/swarm-mail.db: 519 migrated, 0 skipped
  packages/plugin/.opencode/swarm.db: 7036 migrated, 0 skipped
  .opencode/swarm.db: 0 migrated, 1477 skipped (already in global)
```

--------------------------------

### Swarm Core Workflow Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/claude-plugin/skills/swarm-cli/SKILL.md

Illustrates the typical sequence of commands for executing a task within the Swarm ecosystem, from finding solutions to storing learnings.

```bash
swarm memory find "<task keywords>"
swarm hive ready
swarm mail reserve <files>
# Do the work (TDD: red → green → refactor)
swarm progress 50 "message"
swarm memory store "learning" --tags "domain"
swarm complete "summary"
```

--------------------------------

### Example Assets Directory Structure

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/global-skills/skill-generator/references/conventions.md

Illustrates a common organization for assets like templates and images within a skill's 'assets/' directory.

```bash
assets/
├── templates/
│   ├── report.html
│   └── dashboard.html
├── images/
│   └── logo.png
└── boilerplate/
    └── frontend-app/
```

--------------------------------

### Clone and Install UBS Dependency

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/index.mdx

Installs the UBS (Ultimate Bug Scanner) dependency by cloning the repository and performing a local Python installation.

```bash
git clone https://github.com/Dicklesworthstone/ultimate_bug_scanner
cd ultimate_bug_scanner
pip install -e .
```

--------------------------------

### Initialize Project Directory

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/README.md

Initialize the swarm plugin within your project directory. Navigate to your project first.

```bash
cd your-project
swarm init
```

--------------------------------

### Initialize Skills System

Source: https://github.com/joelhooks/swarm-tools/blob/main/SWARM-TESTING-GUIDE.md

Initialize the skills system within a project.

```bash
# Initialize skills in project
swarm tool skills_init
```

--------------------------------

### Install Swarm Plugin Globally via npm

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/README.md

Install the swarm plugin globally using npm after installing the package. Bun is required to run the CLI.

```bash
# After `npm install -g opencode-swarm-plugin`
swarm claude install
```

--------------------------------

### Skill Structure Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/examples/skill/skill-creator/SKILL.md

Illustrates the basic file structure of a skill, including the required SKILL.md and optional bundled resources like scripts and references.

```treeview
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description, tags, tools)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      - Executable code (run with skills_execute)
    └── references/   - Documentation (load with skills_read)
```

--------------------------------

### Install Swarm Mail

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/packages/swarm-mail/index.mdx

Install the swarm-mail package using npm.

```bash
npm install swarm-mail
```

--------------------------------

### Swarm CLI Installation Commands

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/docs/plans/claude-code-plugin-plan.md

Bash commands for installing and managing the Swarm Claude plugin, including path display, local symlinking for development, project-local installation, and uninstallation.

```bash
# Show plugin path (for --plugin-dir during development)
swarm claude path
# Output: /Users/joel/.bun/lib/.../claude-plugin

# Dev-only: symlink for local testing (NOT primary install path)
swarm claude install
# Creates: ~/.claude/plugins/swarm -> /path/to/claude-plugin

# Project-local install for offline usage
swarm claude init
# Creates: .claude/commands/swarm.md, etc. (standalone mode)

# Uninstall dev symlink
swarm claude uninstall
```

--------------------------------

### Clone and Install CASS Dependency

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/index.mdx

Installs the CASS (Cross-Agent Session Search) dependency by cloning the repository, navigating into the directory, and performing a local Python installation. Includes a command to build the index.

```bash
git clone https://github.com/Dicklesworthstone/coding_agent_session_search
cd coding_agent_session_search
pip install -e .
cass index  # Build the index (run periodically)
```

--------------------------------

### Swarm Command Examples

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/claude-plugin/commands/swarm.md

Demonstrates various ways to invoke the swarm command with different planning modes and workflow options.

```bash
/swarm:swarm "task description"              # Full Socratic (default)
```

```bash
/swarm:swarm --fast "task description"       # Skip brainstorming
```

```bash
/swarm:swarm --auto "task description"       # Auto-select, minimal Q&A
```

```bash
/swarm:swarm --confirm-only "task"           # Show plan, yes/no only
```

```bash
/swarm:swarm --fast --to-main "quick fix"    # Fast mode + push to main
```

--------------------------------

### Verify Swarm CLI Installation

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/claude-code-swarm-plugin/README.md

Verify that the swarm CLI has been installed correctly by checking its version.

```bash
swarm --version
```

--------------------------------

### Example Scripts Directory Structure

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/global-skills/skill-generator/references/conventions.md

Demonstrates a typical organization for executable scripts within a skill's 'scripts/' directory.

```bash
scripts/
├── analyze-form.py
├── validate-fields.sh
└── generate-report.js
```

--------------------------------

### Flag Handling for Non-Interactive Setup

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/IMPLEMENTATION-SUMMARY-DB-CONSOLIDATION.md

Parses the `-y` or `--yes` command-line flags to determine if the `setup` command should run in non-interactive mode. This flag is passed as the second argument to the `setup` function, which in turn passes it to `consolidateDatabases`.

```typescript
const yesFlag = process.argv.includes("--yes") || process.argv.includes("-y");
await setup(reinstallFlag || yesFlag, yesFlag);
```

--------------------------------

### Run Swarm Dashboard Development Server

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/swarm-dashboard/README.md

Use these commands to start the development server, build the project, or preview the production build.

```bash
# Development
bun run dev

# Build
bun run build

# Preview production build
bun run preview
```

--------------------------------

### Ship It ASCII Art Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/global-skills/swarm-coordination/SKILL.md

A whimsical ASCII art example of a cow saying 'moo. ship it.'

```ascii
    \   ^__^
     \  (oo)\л_______
        (__)\       )\/л
            ||----w |
            ||     ||

    moo. ship it.

```

--------------------------------

### Dependency Tree Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/global-skills/swarm-coordination/SKILL.md

An example of an ASCII art dependency tree showing the status of epic subtasks.

```ascii
epic-123
├── epic-123.1 ✓ Auth service
├── epic-123.2 ✓ Database schema
├── epic-123.3 ◐ API routes (in progress)
└── epic-123.4 ○ Tests (pending)

```

--------------------------------

### Post-Deploy Notification Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/claude-code-swarm-plugin/skills/openclaw-messaging/SKILL.md

Example of notifying the system agent about a deployment and then sending a message to a user on Telegram.

```bash
openclaw system event --mode now --text "Shipped v1.2.3 to prod. Changes: new auth flow, fixed rate limiter."
openclaw message send --channel telegram --target @joelhooks -m "v1.2.3 live on prod"
```

--------------------------------

### Swarm Workflow Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/swarm-tools/README.md

Outlines a typical workflow for running a swarm task, from user request to decomposition, parallel execution, and final review.

```text
User: /swarm "add user auth"
       ↓
Coordinator: swarm_decompose → hive_create_epic
       ↓
Coordinator: swarm_spawn_subtask × N → parallel workers
       ↓
Workers: swarmmail_reserve → work → hivemind_store → swarm_complete
       ↓
Coordinator: swarm_review → merge → ship
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/global-skills/skill-generator/references/conventions.md

Shows the required YAML frontmatter for a SKILL.md file, including name and description fields.

```yaml
---
name: skill-name
description: Comprehensive description including what it does and when to use it
---
```

--------------------------------

### Coordinator Session Example Output

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/swarm-evals/docs/README.md

Presents the expected output structure for the coordinator-session evaluation, detailing scores for violation count, spawn efficiency, review thoroughness, and time to first spawn.

```text
coordinator-behavior
├─ violationCount: 1.0 (0 violations)
├─ spawnEfficiency: 1.0 (3/3 workers spawned)
├─ reviewThoroughness: 0.67 (2/3 reviewed)
└─ timeToFirstSpawn: 0.90 (45 seconds)
   → overallDiscipline: 0.89 ✅ PASS (bootstrap phase, collecting data)
```

--------------------------------

### Instantiate Memory Adapters for Different Projects

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/packages/swarm-mail/memory.mdx

Demonstrates how to get memory adapters for distinct project paths. It highlights that adapters are cached per project, and using different paths will result in separate databases.

```typescript
// These use different databases!
const adapter1 = await getMemoryAdapter("/project/a");
const adapter2 = await getMemoryAdapter("/project/b");
```

--------------------------------

### Start Ollama Service

Source: https://github.com/joelhooks/swarm-tools/blob/main/apps/web/content/docs/packages/swarm-mail/memory.mdx

Bash command to start the Ollama service if it is not running. This is a troubleshooting step for embedding generation failures.

```bash
ollama serve
```

--------------------------------

### Initialize a New Skill

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/examples/skill/skill-creator/SKILL.md

Use the `skills_init` command to create a new skill's template structure, including placeholder files for SKILL.md, scripts, and references.

```python
skills_init(
  name: "my-skill",
  description: "Initial description",
  directory: ".opencode/skills"
)
```

--------------------------------

### Initialize a New Skill via CLI

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/global-skills/skill-creator/SKILL.md

Alternatively, initialize a new skill using the command-line interface. This command creates the skill directory and generates necessary template files.

```bash
bun scripts/init-skill.ts my-skill --path .opencode/skills
```

--------------------------------

### Bad Skill Description Examples

Source: https://github.com/joelhooks/swarm-tools/blob/main/packages/opencode-swarm-plugin/examples/skill/skill-creator/SKILL.md

Highlights examples of vague or unhelpful skill descriptions that hinder discoverability and proper triggering.

```markdown
**Bad descriptions**:
- "A useful skill" (too vague)
- "Does stuff with files" (not actionable)
```