Key Concepts

Audience: Customer — this page documents key Rulecatch concepts.

This page defines the core terminology used throughout Rulecatch. Understanding these concepts will help you navigate the dashboard, configure rules, and interpret your data.

Sessions

A session is a single interaction between a developer and an AI coding assistant (e.g., Claude Code). A session starts when the developer opens the assistant and ends when they close it or it times out.

Each session captures:

Token usage — Input, output, thinking, and cache tokens consumed
Cost — Estimated API cost based on model pricing
Tool calls — Every tool invocation (file reads, writes, bash commands, etc.)
Lines changed — Lines added and removed across all files
Active time — How long the developer was actively working
Git context — Repository, branch, and commit information

Sessions are the primary unit of analysis in Rulecatch. The dashboard aggregates session data into daily, weekly, and monthly views.

Events

An event is a single data point within a session. Events are the atomic units that hooks capture and send to the API.

Event Types

Type	Description
`session_start`	AI assistant session begins
`session_end`	Session concludes (includes final token/cost deltas)
`tool_call`	AI invokes a tool (Read, Write, Edit, Bash, Glob, Grep, etc.)
`turn_complete`	A conversation turn finishes
`ai_request`	An AI model request with token counts
`code_accept`	Developer accepts AI-generated code
`code_reject`	Developer rejects AI-generated code
`rule_deviation`	A rule violation was detected in the AI's output
`conversation_turn`	A conversation turn with user intervention tracking

Events carry 40+ fields depending on the type — see Event Schema for full details.

Rules

A rule defines a pattern that should be detected in AI-generated code. Rules are the core of Rulecatch's violation detection system.

Rule Components

Component	Description
Name	Human-readable identifier (e.g., "Hardcoded API Key")
Category	Grouping (Security, TypeScript, React, MongoDB, etc.)
Severity	`error`, `warning`, or `info`
Conditions	One or more field/operator/value checks that must ALL match
Fix Time	Estimated minutes to fix a violation

Rule Sources

Template rules — Pre-built rules from Rulecatch's library (200+ templates across 17 categories). Assigned based on your stack selection during onboarding.
Custom rules — User-created rules with custom conditions (Enterprise plan only).
Always-active rules — Special rules (like AI Errors) that apply to all users regardless of stack selection.

Violations

A violation is created when an event matches a rule's conditions. Violations are the primary output of Rulecatch's rule engine.

Each violation records:

The rule that was violated (template or custom)
The event that triggered it (tool call, file path, content)
The file and line number where the violation occurred
Whether it was later corrected (the developer fixed the issue)

Correction Detection

Rulecatch automatically detects when a violation is corrected. When a subsequent tool call modifies the same file and the rule's conditions no longer match, the violation is marked as corrected. This powers the Correction Rate metric.

Hooks

Hooks are shell scripts that Claude Code executes at specific lifecycle points. Rulecatch installs hooks that capture events with zero token overhead — the hooks run outside the AI's context window and consume no tokens.

Hook Events

Hook	When It Fires
`SessionStart`	When a Claude Code session begins
`SessionEnd`	When a session ends
`PostToolUse`	After every successful tool call
`PostToolUseFailure`	After a failed tool call
`Stop`	When Claude Code is stopped

Hooks write JSON event files to a local buffer directory (~/.claude/rulecatch/buffer/). The flush script periodically sends buffered events to the API.

Pooler

The pooler is the client-side component that manages event buffering and delivery. It consists of:

Hook script (rulecatch-track.sh) — Captures events from Claude Code hooks
Flush script (rulecatch-flush.js) — Batches and sends events to the API
Buffer directory (~/.claude/rulecatch/buffer/) — Local event storage
Session token — Authenticated token for API communication

The pooler implements backpressure control, exponential backoff, and circuit breaking to handle API unavailability gracefully.

Zero-Token Overhead

Rulecatch's tracking adds zero tokens to your AI usage. This is achieved by:

Hooks run outside the AI context — They execute as shell commands, not as part of the AI conversation
No prompt injection — No additional text is added to prompts
No response interception — AI responses pass through unmodified
Metadata only — Hooks capture metadata about tool calls, not the full conversation

Your AI token costs remain exactly the same with or without Rulecatch installed.

Zero-Knowledge Encryption

Rulecatch supports zero-knowledge encryption where sensitive data (emails, usernames, file paths) is encrypted on your machine before being sent to the API.

Encryption — AES-256-GCM with PBKDF2 key derivation
Your key — Only you hold the encryption key; Rulecatch cannot decrypt your data
Hashed fields — SHA-256 hashes (truncated to 16 chars) allow grouping without revealing values
Dashboard decryption — Enter your key in the browser to decrypt data client-side

See Encryption for full details.

Regions

Rulecatch operates in two isolated regions for GDPR compliance:

Region	Data Location	API Domain	Dashboard Domain
US	Virginia, USA	`api.rulecatch.ai`	`dashboard.rulecatch.ai`
EU	Frankfurt, Germany	`api-eu.rulecatch.ai`	`dashboard-eu.rulecatch.ai`

Each region has completely independent infrastructure — separate VPS, separate MongoDB clusters, separate containers. US data never touches EU infrastructure and vice versa.

You select your region during account creation. It cannot be changed after signup.

Feature Gating

Access to dashboard features is controlled by your subscription plan. Rulecatch uses a feature matrix that maps features to plans:

Plan	Key Features
Starter ($49/seat/mo)	Overview, Violations, Rules (read-only), Daily Digest email
Pro ($199/seat/mo)	+ AI Sessions, Reports, Full Alert Builder, MCP, Pattern Detection
Enterprise ($499/seat/mo)	+ Versions, Custom Rules, All Alert Channels, SSO, Priority Support

Trial periods give access to Pro-level features for 7 days.

See Pricing and Feature Gating for details.