agentreflex docs

Every agentreflex command — init, add, remove, new, install, uninstall, doctor, and dev.

The CLI is agentreflex, aliased to arx. Both names work.

agentreflex <command> [options]
arx <command> [options]

`init`

Scaffold .reflex/, detect installed agents, wire each one's native hook, and optionally drop in a starter reflex. Interactive.

npx agentreflex init

`add`

Add a reflex or a pack — from the registry (by name), a GitHub path, a URL, or a local path. Reflexes are written into .reflex/ and recorded in config.json.

arx add no-force-push
arx add github:you/reflexes/no-secrets.mjs
arx add https://example.com/no-secrets.mjs
arx add ./no-force-push.mjs

A spec that resolves to a pack.json (a folder containing one, a URL to one, or a registry name listed under packs) installs as a pack: its files are staged into .reflex/packs/<name>/, you're prompted once for any secret it references (stored user-private, reused on reinstall), and its MCP servers / skills / session hooks / reflexes are wired into every agent that can carry them.

arx add acme                             # registry name → the product's own repo
arx add github:acme/acme/packs/acme      # straight from a repo
arx add ./packs/acme                     # local folder (authoring loop)

Pack options (like a self-hosted endpoint) can be overridden with --set:

arx add acme --set acme_url=http://localhost:8000/mcp

`remove`

Remove an installed pack: agent wiring, staged files, config.json entries, and its stored secrets.

arx remove acme

`new`

Scaffold a new reflex file in .reflex/ and register it.

arx new my-reflex

`install`

Wire (or re-wire) the dispatcher into your agents — run it after cloning a repo that already has reflexes.

arx install                 # all detected agents
arx install --agent claude  # just one

`uninstall`

Remove agentreflex's hooks from your agents. Your reflex files stay.

arx uninstall

`doctor`

Show which agents are wired and what each can enforce — and probe every installed pack's MCP servers with a real JSON-RPC initialize, reporting an actionable verdict (connected / unauthorized / host-rejected / not-found / unreachable).

arx doctor

`dev`

Simulate a tool call against your reflexes and print the verdict — no agent needed. This is the way to test a reflex.

arx dev "git push --force origin main"        # a Bash command (the default tool)
arx dev --tool Read --paths .env              # a file-based reflex
arx dev --reflex no-secrets --tool Read --paths .env   # one in-repo reflex, from source
arx dev --event onToolResult --tool Write --paths a.ts # a post-tool side effect

`dev` flag	Meaning
`--tool <name>`	Tool to simulate (`Bash`, `Read`, `Write`, `Edit`…). Default `Bash`.
`--paths <a,b>`	Comma-separated file paths the tool would touch.
`--agent <name>`	Pretend a specific agent is calling. Default `claude`.
`--event <onToolCall\|onToolResult>`	Lifecycle event to run. Default `onToolCall`.
`--reflex <name>`	Test one reflex from `reflexes/<name>` (in the monorepo).
`--file <path>`	Test one reflex file directly, ignoring `.reflex/config.json`.
`--with <json>`	Options passed to the reflex as `ctx.options` (for configurable reflexes).

Flags

Flag	Applies to	Meaning
`--dir <path>`	all	Run as if in another directory.
`--agent <name>`	install, uninstall, dev	Target specific agents (comma-separated).
`--scope <project\|global>`	install, uninstall	Wire the project or your whole machine.
`--global`	install, uninstall	Shorthand for `--scope global`.
`--registry <url>`	add	Resolve names against a different catalog.
`--set <opt=value,...>`	add (packs)	Override a pack's declared options (e.g. a self-hosted endpoint).

arx hook --agent <name> is the machine-facing dispatcher each wired agent calls with a payload on stdin — not a test tool. Piping JSON into it by hand usually does nothing: a pass is silent, a deny prints raw JSON meant for the agent, and without the agent's cwd it loads no reflexes. To test a reflex yourself, use arx dev.

CLI Reference