Rulecatch

AI-Pooler Overview

Audience: Customer — this page documents the AI-Pooler architecture and data flow.

The Rulecatch AI-Pooler is a client-side component that captures AI development events with zero token overhead. It runs on the developer's machine and sends data to the Rulecatch API.

Architecture

┌─────────────────────────────────────────────────┐
│                Developer's Machine                │
│                                                   │
│  ┌─────────────┐     ┌──────────────────────┐   │
│  │ Claude Code  │────→│ Hook Script           │   │
│  │ (AI Session) │     │ rulecatch-track.sh    │   │
│  └─────────────┘     └──────────┬───────────┘   │
│                                  │                │
│                                  ▼                │
│                       ┌──────────────────────┐   │
│                       │ Buffer Directory      │   │
│                       │ ~/.claude/rulecatch/  │   │
│                       │ buffer/*.json         │   │
│                       └──────────┬───────────┘   │
│                                  │                │
│                                  ▼                │
│                       ┌──────────────────────┐   │
│                       │ Flush Script          │   │
│                       │ rulecatch-flush.js    │   │
│                       │                       │   │
│                       │ • Reads buffer files  │   │
│                       │ • Encrypts PII        │   │
│                       │ • Batches events      │   │
│                       │ • Sends to API        │   │
│                       └──────────┬───────────┘   │
│                                  │                │
└──────────────────────────────────┼────────────────┘
                                   │ HTTPS
                                   ▼
                        ┌──────────────────────┐
                        │   Rulecatch API       │
                        │   api.rulecatch.ai    │
                        └──────────────────────┘

Key Properties

Property Value
Token overhead Zero — hooks run outside AI context
Buffer location ~/.claude/rulecatch/buffer/
Config location ~/.claude/rulecatch/config.json
Encryption AES-256-GCM (zero-knowledge, always enabled)
Backpressure Exponential backoff with circuit breaker
Session tokens 24-hour expiry, refreshed every 3 minutes

How It Works

1. Event Capture

Claude Code fires hooks at lifecycle events (session start, tool use, session end). The hook script (rulecatch-track.sh) captures event data and writes a JSON file to the buffer directory.

Each buffer file is a single event:

~/.claude/rulecatch/buffer/1707234567890-tool_call-abc123.json

2. Event Buffering

Events accumulate in the buffer directory. The flush script fires when:

  • The AI-Pooler determines the optimal batch size by negotiating with the API
  • A session ends
  • The user manually runs npx @rulecatch/ai-pooler flush

3. PII Encryption

The flush script always encrypts PII fields before sending:

  • Git email, username
  • File paths
  • Project identifiers

A secure encryption key is auto-generated during init if you don't provide one. You can also supply your own with --encryption-key. See Encryption for details.

4. Backpressure Control

Before sending, the flush script:

  1. Checks local backpressure state (any active backoff?)
  2. Asks the API for capacity (POST /api/v1/ai/pooler/capacity)
  3. Sends events in appropriately-sized batches
  4. Respects delays between batches

See Backpressure for details.

5. API Delivery

Events are sent via POST /api/v1/ai/ingest with:

  • API key in Authorization: Bearer header
  • Session token in X-Pooler-Token header
  • Batched events in the request body

Data Flow Summary

What Where When
Hook fires In Claude Code process Every tool call, session start/end
Buffer write Local filesystem < 1ms per event
Flush trigger After optimal batch size or session end Automatically managed
API delivery HTTPS to regional API 100-500ms per batch
Cleanup Buffer files deleted After successful send

File Locations

File Purpose
~/.claude/hooks/rulecatch-track.sh Hook script (event capture)
~/.claude/hooks/rulecatch-flush.js Flush script (event delivery)
~/.claude/rulecatch/config.json Configuration (API key, region, encryption)
~/.claude/rulecatch/buffer/ Event buffer directory
~/.claude/rulecatch/.session Current session token
~/.claude/rulecatch/.backpressure-state Backpressure state
~/.claude/rulecatch/.paused Subscription pause indicator
~/.claude/rulecatch/flush.log Flush activity log
/tmp/rulecatch-hook.log Hook debug log
~/.claude/settings.json Claude Code settings (hooks registered here)

Monitor-Only Mode

The AI-Pooler supports a monitor-only mode that works without an API key or Rulecatch account:

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

In monitor-only mode:

  • Hooks fire and capture events locally
  • The live monitor TUI shows real-time AI activity
  • No data is sent to any server — flush detects the missing API key and discards buffer files
  • No encryption is configured (not needed since data stays local)
  • MCP server is not installed

This lets developers try Rulecatch with zero friction. Upgrade to full mode anytime by running init again with an API key.

What Gets Tracked

Event Type Data Captured
Session Start Claude version, git context, model
Session End Token deltas, cost, model breakdown, git diff stats
Tool Call Tool name, success/failure, file path, tool input/output content, language, lines changed
Turn Complete Timestamp, user intervention flag

Tool input/output content is captured because the rule engine needs it to detect violations (e.g., hardcoded API keys, SQL injection patterns, insecure code). All PII fields are encrypted before transmission. See Encryption.

What is NOT Tracked

  • Conversation content — No user prompts or AI response text are captured
  • Screenshots or images — Never captured
  • Model context — No injection into AI context window (zero token overhead)

See Also

Installation →