Repository navigation
Releases
Reflex v0.18.2: the plugin never starts another agent
Claude Code plugin (plugin/), for the plugin directory review:
- The plugin never starts another agent session. The System 2 CLI backend (claude -p, codex exec) is removed from the bundle; in the plugin, System 2 is an HTTP API only (Anthropic or OpenAI-compatible) with the key from the sensitive judge_api_key option. A System 2 approval is a silent pass: Claude Code's own permission prompt still decides.
- The build fails if the bundle contains a flag or setting that skips prompts or hooks, or starts any process other than node, git, sed or the terraform, tofu, kubectl and helm binaries it reads plans with.
- System 2 now runs inside the plugin hook's 10 s timeout; a judge that runs out of time asks instead of letting the command through.
Installs through reflex setup keep the CLI backend and behave as in 0.18.1.
Upgrade: /plugin update reflex, or npx @ursuciprian/reflex@0.18.2 setup (outside a Reflex checkout).
Reflex v0.18.1: plugin directory compliance
The Claude Code plugin bundle (plugin/) now passes the plugin directory checks more cleanly:
- Plugin hooks answer only ask or deny, or nothing. No allow, no approve, no rewritten input; the build fails if one appears.
- No icon, test data, example hosts or credential reads in the bundle. The Jev and System 2 keys come only from the plugin's sensitive options.
- Each command runs a plain shell script in scripts/ that checks its arguments and starts one module.
Installs through reflex setup behave as in 0.18.0.
Upgrade: /plugin update reflex, or npx @ursuciprian/reflex@0.18.1 setup (run outside a Reflex checkout).
Reflex v0.18.0: human-last decisions
Reflex decides so you are asked only when it matters: Jev (System One) first, then System 2 (the claude CLI or an API backend), then you, for the always-human class, rule hits, a change freeze or the runaway guard.
Install: /plugin marketplace add ursuciprian/reflex then /plugin install reflex@reflex · or npx @ursuciprian/reflex@0.18.0 setup (run outside a Reflex checkout) · GitHub Action: uses: ursuciprian/reflex@v0.18.0
Changed
- Laya engine:
reflex setup --engine layainstallslaya[serve]==0.3.22(was 0.3.20). Measured head to head with 0.3.20 and Jev 1.13.0 on every golden set on 2026-09-30: every number is the same, and every answer is the same except four gate cases whose state holds a per-process path (at most 0.013 of probability, no decision changed). The checkpoints stay at revision55cf4c4, still the latest. The GUIDE's "Measured against Jev" table is rerun on the current golden sets (199 gate cases, 47 ladder commands) and adds the MCP set, where calibrated Laya matches Jev (0 MISS, 0 over-strict, on 6 cases that reach System 1). Laya stays off by default.
Added
- Human-last by default: when System 1 is unsure and a System 2 is found (the
claudeCLI, elseANTHROPIC_API_KEY),reflex setupturns it on in the supervised profile and with no profile too, so System 2 decides before a human is asked. The always-human class, rule outcomes, a change freeze and the runaway guard still reach a human, and what System 2 hands up is asked in the agent as before.config.json"judge": "off"(orreflex setup --judge off) opts out, and later setups keep it off. Ajudge.backendofnonesaved by an earlier supervised setup is not an opt-out: the next setup picks a System 2 when one is found. reflex statuslists the human-last rungs (rules, read-only and fast lane, the workspace allowlist, System 1, System 2, human), whether each is active and why, and what still reaches a human.- The keyless workspace allowlist (
workspace.mjs):mkdir -p,touch,sed -iwith ones///script on a tracked file (the GNU or the BSD form, following thesedon PATH), andcpormvof a tracked file to a path that does not exist yet pass without an engine, each as one simple command with plain relative paths only. No operator, expansion, redirect, glob, extra flag, dot segment (..,.git,.reflex,.github,.husky), symlink, nested repository or protected path. In enforce mode a checkpoint is taken first and the pass is refused without one, and never in production; anything else goes to the engine or the ladder unchanged.config.json"workspace": falseorREFLEX_WORKSPACE=offturns it off.node workspace.mjs --selfcheck(innpm test) runssetup/tool-gate/golden-workspace.json, which covers the ten bypasses the review of the first attempt (#78) confirmed. - MCP infrastructure preset: an unknown MCP tool on a server named for cloud, clusters, IaC, a database or a code host (
aws,awslabs,kubernetes,k8s,kubectl,terraform,tfc,gcp,gcloud,azure,postgres,mysql,mongodb,dynamodb,database,db,supabase,github,gitlab) or any server name containingprodasks keyless instead of being logged only; Jev still judges it with a key. The match reads the server name alone, word by word, so aupdate_databasetool on a notion server is not infra anddbtis notdb.config.json"mcp": {"infra": false}turns it off. npm run eval-compareruns the MCP golden set too (--suites mcp).
Fixed
- A checkpoint whose
git stash createfailed (an intent-to-add entry, a read-only.git) was recorded as HEAD, soreflex checkpoints restorecould not bring back uncommitted changes. It is now no checkpoint at all. - Engine jev with no API key (for example a curl install without
--keychain): in shadow mode every command the rules leave to the engine was logged as an ask with the rule "jev unavailable (Error: no API key for typesafe: ...)". Shadow enforces deterministic rules only, so an engine that gives no answer (a missing key, an unreachable host, a timeout, a malformed answer) now passes, and the trace records the reason. Enforce mode keeps the policy fallback, which asks. - A missing engine key is now reported as a configuration error, not an outage.
reflex statusandreflex doctorshow "Jev engine has no API key: every engine decision falls back; run reflex setup --keychain or set TYPESAFE_API_KEY", also when only the hooks' environment lacks the key. The Claude Code hook shows the warning once per session as a systemMessage, not once per command. reflex setupwith a saved engine jev and no key found (environment, Keychain or provider options) now picks the local engine and says so. With--engine jev,--providerorREFLEX_ENGINEit keeps jev and prints a loud warning that suggests--keychain.
Docs: https://ursuciprian.github.io/reflex/ · Changelog: https://github.com/ursuciprian/reflex/blob/main/CHANGELOG.md
Reflex v0.17.1: fix a crash on paths with an unclosed [
Fix: a path with an unclosed [ crashed the self-protection check, so reflex learn and reflex replay stopped in 0.17.0. The pattern now fails closed (the path counts as touching Reflex). In hooks, the fail-closed wrapper already turned the crash into an ask.
Upgrade: npx @ursuciprian/reflex@0.17.1 setup (run outside a Reflex checkout), or /plugin update reflex.
Reflex v0.17.0: MCP and protected-file gate, reflex learn, plugin bundle
Reflex makes AI coding agents prod-safe for infra teams: a pre-execution hook for Claude Code, Codex CLI, opencode and pi that judges each shell command, MCP call and protected-file write by where it points and what it will change, then runs it, asks a human, or blocks it.
Install: /plugin marketplace add ursuciprian/reflex then /plugin install reflex@reflex · or npx @ursuciprian/reflex@0.17.0 setup (run outside a Reflex checkout) · GitHub Action: uses: ursuciprian/reflex@v0.17.0
Added
- MCP server guardrails: the gate judges MCP tool calls before they run, in Claude Code and Codex (
mcp__<server>__<tool>), opencode, pi and Hermes. Rules insetup/tool-gate/mcp.jsonask on a destructive verb in the tool name (delete, destroy, drop, terminate, remove, purge, truncate, force, reset, rollback, uninstall and more), a scale to zero, a bucket policy, security group or IAM change, destructive SQL and an HTTP DELETE, and deny when an argument or the server points at production. A shell command in an argument goes through the shell rules. Read-like tools pass unlogged; an unknown tool is logged keyless, judged by Jev with a key, or asks with"mcp": {"unknown": "ask"}. The freeze, queue, runaway guard, trace, audit and webhook apply. A team policy can addmcprules, stricter only. - Protected files: a write by Edit, Write, MultiEdit, NotebookEdit,
apply_patchor the opencode, pi and Hermes file tools to.github/workflows/,.gitlab-ci.yml, production paths, production Terraform, tfvars and Dockerfiles,.reflex/, agent settings and hooks,.mcp.json, git hooks or shell startup files asks, with the path and why in the reason (setup/tool-gate/protected.json).config.jsonprotectedand a team policyprotectedlist add globs. npm run eval-mcp: 83 golden MCP and file-write cases (setup/tool-gate/golden-mcp.json), keyless or with Jev.reflex learn: fast-lane entries from what you approved yourself, to reduce permission prompts
over time. It reads only a human's answers (approval queue items approved or denied withreflex queue, Reflex asks and Claude Code permission dialogs that then ran, refusals, and asks left
unanswered for 10 minutes), never a System 1 allow or a System 2 verdict. It reusesreflex suggest's templates and safety proof and proposes a shape only when it was approved--mintimes
(default 3) in at least 2 sessions and never refused, and is not production or always-human.
Destructive, prod, secret, tamper, freeze and MCP commands are never learned. It prints the humans
per 100 commands before and after on your transcripts.--writeasks on the terminal (or needs
--yes) and recordsid,learned_atandlearned_fromper entry;--list,--forget <id>and
--prunereview and remove learned entries;--teamprints a.reflex/policy.jsonfastlane
snippet.reflex statusnotes how many approved shapes could stop asking;reflex doctorflags
learned entries unused for 60 days. An agent runningreflex learn --write,--forgetor
--prunegets a tamper ask. CLI only: the Claude Code plugin does not ship it. On the maintainer's
history (32,001 commands, 30 days, keyless) it proposed nothing: 50.4 humans per 100 before and
after, because the commands that ask there are interpreters,sed -i,curl,ghandgit.
A learned entry is pinned to the sha256 of the scripts it runs; an edited script stops passing.
Changed
- gate.mjs split into modules; no behaviour change.
config.mjs(settings, validation, redaction),
shell.mjs(words, heredocs, rule spellings),scripts.mjs(local scripts),readonly.mjs
(read-only detection, pipelines),rules.mjs(checkRules, the large-command deny rules),
tamper.mjs,jev.mjs(context, key, provider call, cache, jevJudge) andselfcheck.mjs.
gate.mjs keeps the CLI, precheck, decide and the hook adapters and re-exports every name that
moved. The new modules are in the plugin bundle and on the tamper list like gate.mjs.
Security
- User fast lane: a script body with inline interpreter code (
node -e,python -c,sh -c,
deno eval) no longer qualifies, andreflexand the gate's entry points are denied words. - Tamper: a local script (package.json script, Makefile recipe, shell file) that runs
reflex setup,
reflex queue approve|deny,reflex suggest --writeorreflex learn --writeis a tamper ask,
also in the bundled fast lane (npm run lint).reflex suggestorreflex learnwith its flags in
a variable,"$@",xargs,evalor a function is a tamper ask too. - Tamper: more spellings of a shell write into the Reflex data directory (
REFLEX_DATA_DIR, else
$XDG_STATE_HOME/reflexor~/.local/state/reflex) or the config directory are tamper asks: from
a working directory inside or above it with nocd(echo x >> reflex/trace.jsonlfrom
~/.local/state,echo x >> ../feedback.jsonlfromqueue/), a relativecd reflexfrom the
parent, a..climb, a glob (refle?,[r]eflex),./or//in the path, another case, a
symlinked spelling, an archive unpacked in the parent orcp/rsyncinto it (tar -xf,tar -C,
cp -r x/. .), and a Reflex file under a variable the command does not set ($D/trace.jsonl,
${D}feedback.jsonl,cd $Q && tee q-1.json).$PWDand$TMPDIRare resolved. A local script
is read the same way. A(cd /tmp)subshell no longer leaves the next command resolved to/tmp,
andcd ~-iscd -. A custom data or config directory is matched only as itself or a path in
it, not a sibling that starts with its name. Not caught: a bare variable (echo x >> $F), a
generic file name such asconfig.jsonunder a variable, or an unknown program run in the parent
that writesreflex/without naming it.reflex learntrusts these logs as far as this check
protects them; the GUIDE says so. - Importing a Reflex file no longer does anything.
install.mjs,eval.mjs,eval-ladder.mjs,
eval-compare.mjs,eval-instructions.mjs,status.mjs,report.mjs,audit.mjs,replay.mjs,
test.mjs,hook.mjs,scripts/reflex,scripts/reflex-reviewandscripts/build-plugin.mjs
ran their work at the top level, so animport("./install.mjs")(a review agent reading the code)
rewrote a real~/.claude/settings.json. Every script now runs only when started directly
(isMaininfailsafe.mjs: the real path ofimport.meta.urlagainst the real path of
process.argv[1], so a symlinkedreflexstill runs).node install.mjs ...,reflex setupand
npm run evalwork as before. A test imports every*.mjsat the top, inadapters/,
scripts/androuter/in a child withHOME,CLAUDE_CONFIG_DIR,XDG_CONFIG_HOME,
XDG_STATE_HOMEandTMPDIRin an empty scratch directory, and fails when anything appears or
changes there or a process is started. - Tamper: the files the tamper rule protects inside the checkout are read from the checkout instead
of a hand-kept list, which had missedtools.mjs,freeze.mjs,notify.mjs,mcp.mjs,
laya.mjs,learn.mjs,status.mjs,replay.mjs,suggest.mjs,audit.mjs,
eval-compare.mjs,test.mjsand more. Covered now: every top-level*.mjs,*.js,*.shand
*.jsonfile (install.sh,package.json,.mcp.json) and everything undersetup/,
scripts/,adapters/,hooks/,router/,routing/,plugin/,commands/,skills/,
.claude-plugin/,.codex-plugin/and.agents/. The gate's selfcheck fails when a file of the
checkout is neither covered nor listed as not run by Reflex (docs, site, examples and the like).
Fixed
- Hermes: the injection guard's
post_tool_callmatcher named MCP toolsmcp__.*, but Hermes names themmcp_<server>_<tool>, so MCP results were never scanned there. It ismcp_.*now. - Plugin bundle: the stripped gate, run without
--pluginand with no key source, no longer calls the Jev provider without a key; it asks. A test checks that no request is sent. - The npm package no longer ships
.claude-plugin/marketplace.json, which points atplugin/(installed from git, not npm).
Docs: https://ursuciprian.github.io/reflex/ · Full changelog: https://github.com/ursuciprian/reflex/blob/main/CHANGELOG.md
Reflex v0.16.0: infra guardrails, plugin bundle, CI policy check
Reflex is an open-source pre-execution hook for Claude Code, Codex CLI, opencode and pi. It judges every shell command by where it points and what it will change, then lets it run, asks a human, or blocks it.
GitHub Action
- uses: ursuciprian/reflex@v0.16.0
with:
commands: |
terraform plan
kubectl get pods -n prod
Validates .reflex/policy.json and fails the job when a policy change would deny one of your expected commands. Keyless; no secrets needed.
In this release
- OpenTofu, Terragrunt and helm guardrails
- Read-only allowlist (opt-in), policy packs (
reflex policy init --pack aws) - Documentation site: https://ursuciprian.github.io/reflex/
- Plugin directory bundle, fail-closed hooks, Jev via OpenRouter, Cloudflare or Vercel
Full Changelog: v0.15.0...v0.15.0