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

> Install the rules module in activeloopai/hivemind easily. Follow this guide to provision notification rules and create SQLite tables using the Hivemind CLI.

- Repository: [Activeloop/hivemind](https://github.com/activeloopai/hivemind)
- Tags: how-to-guide
- Published: 2026-06-11

---

**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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/src/deeplake-api.ts) to create or update the SQLite table
- Registers the notification hooks that **[`src/context-renderer.ts`](https://github.com/activeloopai/hivemind/blob/main/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:

```bash
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:

```bash
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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/src/cli/rules.ts)**.

### List Existing Rules

View all registered rules in the `hivemind_rules` table:

```bash
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:

```bash
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`):

```bash
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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/src/notifications/rules/registry.ts) to format the output correctly.

**[`tests/shared/rules.test.ts`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/src/deeplake-api.ts)** successfully created the SQLite database during installation. The test suite in **[`tests/shared/rules.test.ts`](https://github.com/activeloopai/hivemind/blob/main/tests/shared/rules.test.ts)** demonstrates the expected behavior for rule insertion and rendering, which you can reference to validate your setup.