Contributing

Two ways to get a reflex in front of other people: contribute it to the commons as an official reflex, or share it from your own repo as a community reflex.

Official reflexes

Official reflexes live in /reflexes and are installable by short name (arx add <name>). Each is a small package — and the monorepo gives you three commands to scaffold, run, and validate one without hand-wiring anything.

git clone https://github.com/agentreflex/agentreflex && cd agentreflex
pnpm install

1. Scaffold it. Generates the full package — src/index.ts, reflex.json, test/, package.json, tsconfig.json, README.md — with a runnable test already in place.

pnpm reflex:new no-rm-rf --title "No rm -rf" --desc "Blocks recursive rm of dangerous targets."

2. Write + run it. Edit reflexes/no-rm-rf/src/index.ts, then build-and-simulate in one step. Any arx dev flag passes through, so you can test file-based reflexes too:

pnpm reflex:dev no-rm-rf "rm -rf /"            # a shell command
pnpm reflex:dev no-secrets --tool Read --paths .env   # a file-based reflex

For a tight loop, run pnpm --filter ./reflexes/no-rm-rf build --watch in one terminal and arx dev --reflex no-rm-rf … in another.

3. Test + validate before you PR.

pnpm test no-rm-rf      # your catch + non-catch tests
pnpm reflex:check       # validates every reflex: manifest, declared capabilities vs code, tests, README

reflex:check is what CI runs — it fails if the manifest is wrong, a declared decision is never returned, the entry doesn't build, or the test/README is missing. Get it green, then open a PR.

Official reflexes are held to a higher bar: single-purpose, an accurate reflex.json (the $schema field gives you live validation in your editor), and a test that proves both the catch and the non-catch. Maintainers review the source before merge, and the catalog is rebuilt on release.

Community reflexes

Anything else is welcome from your own repo. Publish the reflex as a single .mjs file and share the path — users install it directly:

arx add github:you/reflexes/my-reflex.mjs

Add an entry to awesome-reflexes so others can find it.

Guidelines

• Keep reflexes small and single-purpose; compose rather than bundle.
• Reach for deny/ask deliberately — prefer the narrowest rule that holds.
• Be shell-aware: use parseCommand so cd x && … can't slip past a check.
• Declare what the reflex does in reflex.json — no surprises.