Reflex

Portable guardrails for any agent runtime.

Safety rules as data, not code. Define what your agent can and can't do in YAML, and Reflex enforces it -- across Claude Code, MCP servers, Cursor, or any runtime with an adapter.

Why Reflex

Agent safety shouldn't be hardcoded into a single platform's hook system. Reflex separates what the rules are from where they run:

• Rules are YAML files. Readable, versionable, shareable.
• Core rules can't be disabled. Tier enforcement prevents agents from weakening their own guardrails.
• One rule set, many runtimes. Write rules once, enforce them everywhere your agent operates.

Install

npm install @fozikio/reflex

Quick Start

import { RuleEngine, CORE_RULES, loadRuleDirectory } from '@fozikio/reflex';

// Initialize with core safety rules
const engine = new RuleEngine({ allowed_roots: 'D:/projects, /home/user' });
engine.addRules(CORE_RULES);

// Load custom rules from YAML files
const customRules = await loadRuleDirectory('./rules');
engine.addRules(customRules);

// Evaluate an event
const results = engine.evaluate({
  event: 'file_write',
  file_path: '/etc/passwd',
  content: 'something dangerous',
});

// Check if an action is allowed
if (!engine.isAllowed({ event: 'bash_command', command: 'rm -rf /' })) {
  console.log('Blocked by reflex');
}

Rule Format

Rules are YAML files with a flat, declarative structure:

name: block-dangerous-rm
version: 1
tier: core
category: safety
description: Block catastrophic shell commands
events: [bash_command]
conditions:
  - field: command
    op: regex
    pattern: 'rm\s+-rf\s+[/~.]'
action: block
severity: critical
message: "Destructive command blocked: {{command}}"
override:
  allow_disable: false
  allow_downgrade: false

Rule Fields

| Field | Type | Description | |-------|------|-------------| | name | string | Unique rule identifier | | version | number | Rule version (for evolution tracking) | | tier | core | recommended | custom | Enforcement tier | | category | safety | quality | style | cognitive | Rule category | | description | string | Human-readable description | | events | array | Events that trigger evaluation | | conditions | array | All must match for rule to trigger | | action | block | warn | log | What happens when triggered | | severity | critical | high | medium | low | info | Severity level | | message | string | Message shown when triggered (supports {{var}} templates) | | override | object | Whether the rule can be disabled or downgraded |

Events

| Event | Triggers on | |-------|-------------| | bash_command | Shell command execution | | file_write | New file creation | | file_edit | Existing file modification | | file_delete | File deletion | | prompt_submit | User prompt submission | | session_start | Agent session starting | | session_stop | Agent session ending | | tool_call | Any tool invocation | | post_tool | After a tool completes | | any | All events |

Condition Operators

| Operator | Behavior | |----------|----------| | matches | Glob-style matching (comma-separated patterns, * wildcards) | | not_matches | Inverse of matches | | contains | Substring check | | not_contains | Inverse of contains | | equals | Exact string match | | not_equals | Inverse of equals | | starts_with | Prefix check | | ends_with | Suffix check | | regex | Full regex match |

Template Variables

Rule messages and condition patterns support {{variable}} templates. Variables are set at engine initialization and can reference event data:

const engine = new RuleEngine({
  allowed_roots: 'D:/projects, /home/user',
  owner: 'idapixl',
});

message: "Write blocked: {{file_path}} is outside {{allowed_roots}}"

Tier Enforcement

Rules have three tiers with different enforcement guarantees:

| Tier | Can disable? | Can downgrade? | Use case | |------|-------------|----------------|----------| | core | No | No | Safety invariants (write boundaries, destructive command blocking) | | recommended | Yes | Yes | Best practices (credential checks, style rules) | | custom | Yes | Yes | User-defined rules |

Core rules ship with the package and cannot be weakened by configuration:

import { CORE_RULES } from '@fozikio/reflex';
// write-boundary, destructive-commands, path-traversal, credential-protection

API

RuleEngine

const engine = new RuleEngine(variables?: Record<string, string | string[]>);

engine.addRule(rule: ReflexRule): void;
engine.addRules(rules: ReflexRule[]): void;
engine.setVariable(key: string, value: string | string[]): void;

// Returns all triggered rules
engine.evaluate(event: ReflexEventData): EvaluationResult[];

// Returns only blocking results
engine.getBlocks(event: ReflexEventData): EvaluationResult[];

// Returns true if no blocking rules trigger
engine.isAllowed(event: ReflexEventData): boolean;

loadRuleFile / loadRuleDirectory

// Load a single YAML rule
const rule = await loadRuleFile('./rules/my-rule.yaml');

// Load all .yaml/.yml files from a directory (recursive)
const rules = await loadRuleDirectory('./rules', config?);

The optional ReflexConfig lets you disable specific rules by name (respecting tier enforcement):

const config: ReflexConfig = {
  allowed_roots: ['D:/projects'],
  disabled_rules: ['warn-debug-code'],  // only works for recommended/custom tier
  rule_dirs: ['./rules', './extra-rules'],
};

Contributing

See the Contributing Guide. Report security issues via SECURITY.md.

Related Projects

• cortex-engine — Cognitive memory layer for AI agents (ships with Reflex rules)
• sigil — Agent control surface
• fozikio.com — Documentation and guides
• r/fozikio — Community

Background

Reflex is the successor to Hookify, a Claude Code plugin that used markdown files with YAML frontmatter for hook rules. Reflex takes the same idea -- rules as data -- and makes it portable, typed, and enforceable across any agent runtime.

Part of the Fozikio agent toolkit.

License

MIT