Installation

Audience: Customer — this page documents how to install and configure the AI-Pooler.

Set up the Rulecatch AI-Pooler to start tracking your AI development sessions.

Prerequisites

Node.js 18 or later
Claude Code installed and configured
A Rulecatch account with an API key (for full mode) — find it at Dashboard → Settings

Quick Setup

Full Mode (with account)

npx @rulecatch/ai-pooler init --api-key=dc_your_key_here

Follow the interactive prompts to configure region and encryption.

Monitor-Only Mode (free, no account needed)

npx @rulecatch/ai-pooler init --monitor-only

Watch your AI coding activity in real-time without creating an account. No data is sent to any server — everything stays local. Start the live monitor:

npx @rulecatch/ai-pooler monitor

Upgrade to full mode anytime by running init again with an API key.

Init Options

Option	Description	Default
`--api-key=KEY`	Your Rulecatch API key (starts with `dc_`)	Interactive prompt
`--monitor-only`	Skip API key — monitor mode only (no dashboard)	`false`
`--region=us\|eu`	Data region	Auto-detected from account
`--project-id=NAME`	Override auto-detected project name	Git remote or directory name
`--encryption-key=PWD`	Encryption password (min 8 chars)	Auto-generated if omitted
`--batch-size=N`	Events before auto-flush	`20`

What Init Does

The init command:

Validates the API key against the Rulecatch API
Creates config directory at ~/.claude/rulecatch/
Writes config file at ~/.claude/rulecatch/config.json
Installs hook script at ~/.claude/hooks/rulecatch-track.sh
Installs flush script at ~/.claude/hooks/rulecatch-flush.js
Registers hooks in ~/.claude/settings.json
Creates buffer directory at ~/.claude/rulecatch/buffer/

Config File

Full mode:

{
  "apiKey": "dc_...",
  "projectId": "my-project",
  "region": "us",
  "batchSize": 20,
  "salt": "base64-encoded-salt",
  "encryptionKey": "your-encryption-password"
}

Monitor-only mode:

{
  "apiKey": "",
  "projectId": "my-project",
  "region": "us",
  "batchSize": 20,
  "salt": "",
  "encryptionKey": "",
  "monitorOnly": true
}

Field	Description
`apiKey`	Your `dc_` prefixed API key (empty in monitor-only mode)
`projectId`	Auto-detected from git remote or directory name
`region`	`us` or `eu` — determines which API endpoint is used
`batchSize`	Number of events buffered before auto-flush (default: 20)
`salt`	Randomly generated salt for encryption
`encryptionKey`	Your encryption password (auto-generated if not provided)
`monitorOnly`	Present and `true` in monitor-only mode
`autoGeneratedKey`	Present and `true` if the encryption key was auto-generated

Hook Registration

The init command registers all 14 Claude Code hook types in ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 30 }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 30 }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "PreToolUse": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "PostToolUse": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "PostToolUseFailure": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "PermissionRequest": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "Notification": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "SubagentStart": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "SubagentStop": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "TeammateIdle": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "TaskCompleted": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }],
    "PreCompact": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/rulecatch-track.sh", "timeout": 10, "async": true }] }]
  }
}

SessionStart and SessionEnd run synchronously (30s timeout) to ensure session data is captured. All other hooks run asynchronously to avoid blocking Claude Code.

Verify Installation

After installing, verify everything is set up:

npx @rulecatch/ai-pooler status

You should see:

Rulecatch Status

Collection:    + Active

Config:        + Found
  API key:     dc_a1b2...
  Region:      US (Virginia)
  Encrypted:   Yes

Hook script:   + Installed
Flush script:  + Installed
Hooks config:  + Registered

Buffer:        0 events pending
Session token: Not acquired yet

Hook log:      o No activity yet

Backpressure:  + Healthy

Encryption Setup

Encryption is always enabled — PII fields (emails, usernames, file paths) are encrypted on your machine before being sent to the API. Rulecatch servers never see plaintext PII.

If you don't provide an encryption key during init, a secure key is automatically generated for you. You can also provide your own:

Custom Key (During Init)

npx @rulecatch/ai-pooler init --api-key=dc_... --encryption-key=my-secret-passphrase

Update Key Later

To change your encryption key, run init again:

npx @rulecatch/ai-pooler init --api-key=dc_... --encryption-key=my-secret-passphrase

Viewing Your Key

npx @rulecatch/ai-pooler config --show-key

Save this key — you'll need it to decrypt data in the dashboard.

Uninstall

To completely remove Rulecatch tracking:

npx @rulecatch/ai-pooler uninstall

This removes:

Hook scripts
Config directory and files
Buffer directory and events
Hook registrations from settings.json

Next Steps

After installation:

Start a Claude Code session — Events will be captured automatically
Check the dashboard — Visit your dashboard to see data appearing
Configure rules — Select your tech stack to activate relevant rules
Set up alerts — Get notified when violations are detected