How to Install the Rules Module in activeloopai/hivemind: Complete Setup Guide

You install the rules module by installing the global Hivemind CLI package (npm install -g @deeplake/hivemind) and running hivemind install, which automatically provisions the notification rules and creates the necessary SQLite tables.

The rules module in activeloopai/hivemind lives under src/notifications/rules/ and powers rule-based notifications that appear at session start, such as "local mined" alerts and referral invites. Rather than installing this module in isolation, you deploy it as part of the complete Hivemind CLI package, which registers the notification hooks and initializes the underlying data structures. This guide walks through the exact installation steps and explains how the source code wires everything together.

Understanding the Rules Module Structure

The rules source code resides in src/notifications/rules/, with the built-in rule definitions exported from src/notifications/rules/registry.ts. These rules are not standalone plugins; they integrate with the Hivemind runtime through a SQLite-backed table called hivemind_rules.

When you run the installation commands, the CLI performs three critical actions:

• Copies the rule source code from src/notifications/rules/ to your local installation
• Calls ensureRulesTable() in src/deeplake-api.ts to create or update the SQLite table
• Registers the notification hooks that src/context-renderer.ts queries at runtime

Step-by-Step Installation

Install the Global CLI Package

Run the npm command to pull the latest Hivemind package, which bundles the rules source code and all dependencies:

npm install -g @deeplake/hivemind

This command installs the hivemind binary globally and copies the rule registry files to your system.

Run the Hivemind Install Command

Execute the installation wizard to detect your AI assistants and provision the rules infrastructure:

hivemind install

This command detects installed assistants (Claude, Cursor, Codex, OpenClaw, Hermes, pi) and writes the appropriate hook files. Critically, it invokes the ensureRulesTable() function in src/deeplake-api.ts, which creates the SQLite-backed hivemind_rules table that stores active notification rules.

Verifying and Managing Rules

After installation, you can manage rules through the CLI commands defined in src/cli/rules.ts.

List Existing Rules

View all registered rules in the hivemind_rules table:

hivemind rules list

This queries the database and displays built-in rules like welcome, referralInvite, and localMined, along with any custom entries you have added.

Add Custom Rules

Insert new notification rules that trigger based on specific conditions:

hivemind rules add \
  --match "^SELECT .* FROM \"hivemind_sessions\".*LIMIT 10$" \
  --text "🔔 You've hit 10 sessions – time to review your progress!" \
  --scope team

This command writes directly to the hivemind_rules table, which the runtime reads during context rendering.

Remove Rules

Delete a rule by its ID (retrieved from hivemind rules list):

hivemind rules remove --id rule-12345

This updates the SQLite table and removes the rule from the next session's context.

How the Installation Works Under the Hood

The hivemind install command orchestrates the rules module setup through several interconnected components:

src/deeplake-api.ts contains the ensureRulesTable() function that executes SQL to create the hivemind_rules table if it does not exist. This table schema supports rule matching patterns, notification text, and scoping parameters.

src/context-renderer.ts queries this table at runtime to build the "HIVEMIND RULES" block injected into every agent's context. The renderer uses the rule registry from src/notifications/rules/registry.ts to format the output correctly.

tests/shared/rules.test.ts validates this entire pipeline, confirming that rule rows are properly inserted, queried, and rendered across different assistant types.

Summary

• Install the global package with npm install -g @deeplake/hivemind to obtain the rules module source code located in src/notifications/rules/.
• Run hivemind install to execute ensureRulesTable() in src/deeplake-api.ts, which creates the SQLite hivemind_rules table required by the runtime.
• Manage rules using hivemind rules list, add, and remove commands implemented in src/cli/rules.ts.
• The rules module integrates automatically with Claude, Cursor, Codex, and other supported assistants through the context renderer in src/context-renderer.ts.

Frequently Asked Questions

Is the rules module available as a separate npm package?

No, the rules module is bundled within the @deeplake/hivemind package and cannot be installed independently. The source code lives in src/notifications/rules/ and is deployed automatically when you install the CLI globally.

Why do I need to run hivemind install after the npm install?

The npm command only downloads the code. Running hivemind install executes the setup logic, including the ensureRulesTable() function that creates the local SQLite database and the hivemind_rules table that stores your notification rules. Without this step, the context renderer in src/context-renderer.ts would find no data to display.

Where are the built-in rules defined?

Built-in rules are exported from src/notifications/rules/registry.ts. This registry defines rule objects for notifications like welcome messages, referral invites, and local mining alerts. These defaults are loaded into the hivemind_rules table during the installation process.

How do I debug if rules are not showing up in my assistant?

First, verify the table exists by running hivemind rules list. If the table is empty, check that src/deeplake-api.ts successfully created the SQLite database during installation. The test suite in tests/shared/rules.test.ts demonstrates the expected behavior for rule insertion and rendering, which you can reference to validate your setup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}