Repository navigation
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