reflex

---

Install

/plugin marketplace add alumkal/claude-reflex
/plugin install reflex

Run /reflex:reflex-init in your codebase to get started.

The pitch

Claude is fast, confident, and occasionally wrong. You already know the patterns you keep having to correct — reading .env, rewriting your spec doc, re-running rm -rf. Encode that knowledge once, have it applied every time.

{
  "name": "disallow-read-env",
  "on": "read",
  "pattern": ".*\\.env",
  "action": "reject",
  "message": "DO NOT read .env directly!"
}

Now the agent can't read .env. It sees your message instead.

Three actions, that's the whole model

Action	What happens
proceed	Allow the call, append your message to the agent's context. Nudge.
pause	Block once with your message. If the agent repeats the exact same call, it goes through. Confirm.
reject	Block the call outright with your message. Hard stop.

Matches run on file paths (Read, Edit, Write, NotebookEdit) or command strings (Bash). Rules live in .reflex/reflex.json — check it in, share it with your team.

Skills

Once installed, bootstrap your rules from inside Claude Code:

• /reflex:reflex-init — scans your project, proposes up to 5 candidate rules for you to pick.
• /reflex:reflex-add <sentence> — "pause me before I run rm -rf" → rule, appended.

A rule you'll probably want

{
  "name": "before-commit",
  "description": "Double-check staging before committing",
  "on": "bash",
  "pattern": ".*git commit.*",
  "action": "pause",
  "message": "Run `git status` first to make sure no junk is staged."
}

First git commit: blocked, reminder shown. Claude checks git status, then retries the exact same commit → goes through.

"Why not just put it in CLAUDE.md?"

Because CLAUDE.md is a suggestion. Reflex is a tripwire.

• Deterministic, not advisory. A regex always fires. A rule buried on line 87 of CLAUDE.md gets skimmed, forgotten, or de-prioritized as the context fills up.
• Fires at the moment of action. The message lands when the tool is about to run — the strongest possible attention signal. Rules at the top of the session decay; tripwires don't.
• Can actually block. CLAUDE.md cannot stop rm -rf. A reject rule can.
• Pause-then-proceed is only possible here. "Block this once, let it through on retry" is a control flow CLAUDE.md can't express.
• Pay for what matches. Rules inject tokens only when triggered. A 40-line "DO NOTs" section in CLAUDE.md costs you those tokens on every turn.
• Less cognitive load — for humans too. A CLAUDE.md stuffed with defensive rules is noise when you're reading it and noise when the agent is parsing it. Reflex hides the rules until they matter, so CLAUDE.md stays a document you actually want to read.

Use CLAUDE.md for how we work. Use reflex for what must not happen.

How it works

One PreToolUse hook, ~200 lines of stdlib Python. It full-matches your regex against the path or command, and the most restrictive matching action wins (reject > pause > proceed). Pause state lives in $CLAUDE_PLUGIN_DATA, capped at 256 entries per project. Malformed reflex.json logs a warning and gets out of the way — your agent never freezes.

See reflex-format.md for the full schema, capture-group substitution (\1, \g<name>), and more examples.

Requirements

Python 3.10–3.14. No third-party deps.