Healer

Use the healer to fix a locator that no longer finds its element, with a suggestion you review first.

A nightly job fails because a button’s id changed. The next morning you find a heal in Reflex: the old and new selector, why Reflex thinks it is the same element, and whether a rerun with the fix went green. Accept turns it into a pull request. Nothing in your project changes until a person accepts.

What gets healed

Only locators that no longer find their element. Reflex never heals assertion failures, application errors (such as an HTTP 5xx), infrastructure or configuration problems, or script errors. The run digest names the kind of failure.

How a suggestion is made

When a job or suite script fails on a missing element, Reflex looks at the replay page, finds the element the old selector pointed at and writes durable selectors for it. A candidate is kept only if:

• exactly one element matches;
• it is similar to the element the old selector last found;
• it is stable: no generated ids, hashed class names or positional indexes.

One broken selector hit by a hundred runs produces one heal. Healing needs the replay, so it does not work with replay: off.

Review heals

Open Heals in the project menu. To review lists new suggestions and Verified those whose verification run was green. A heal shows the old and new selector, the evidence, the screenshot at the failure, the file diff and other candidates. You can edit the selector before accepting; Reflex checks it again.

Verify reruns the job on one of your agents with the fix applied, without touching your files. The heal is Verified only if that run is green. Verification runs send no notifications.

Accept needs the Review heals permission (REVIEW_HEALS, which owners and admins have). What happens depends on the project:

Project	Accept does
Git (GitHub, GitLab, Azure DevOps, Gitea)	Creates branch reflex/heal-<id>, commits the change and opens a pull request with the evidence.
Git (OneDev)	Pushes the branch. Open the pull request yourself.
SFTP or files managed in Reflex	Writes the change after keeping a backup in .reflex-backup/.
No push access	Offers the patch as a download.

If the old selector lives in locators.yaml, the change is one entry. Otherwise every literal in your scripts is patched. If your files changed meanwhile, Accept stops with a conflict: sync and review again.

Reject takes an optional reason. The same fix is not suggested again.

Healing modes

Set the mode per job or in reflex.yaml:

version: 1
defaults:
  healing: suggest
jobs:
  nightly-orders:
    script: flows/orders.lua
    healing: heal

Mode	After a locator failure
off	Nothing.
suggest (default)	The run fails as before and a heal appears in the inbox.
heal	If a rule-based, high-confidence candidate exists, Reflex reruns the job once with it. A green rerun counts as passed with healing, never plain green. Nothing is committed.

AI candidates are never used automatically.

Add an AI model (optional)

In the AI settings of your account or project, choose a provider and a model. When the rule-based result is not convincing, the model may add one candidate. It sees the failed call, the old selector and a masked HTML excerpt, and its answer goes through the same checks. Keys stay on the server, and a daily budget limits cost.

Let your own agent help

Your coding agent can add suggestions to the same inbox, with the same checks.

reflex heal list
reflex heal show <heal-id>
reflex heal propose --run <run-id> --selector "role=button[name='Place order']" --verify
reflex heal verify <heal-id>
reflex heal patch <heal-id>

Accepting and rejecting is a human decision in the web UI. reflex heal accept and reflex heal reject (and the MCP tools accept_heal and reject_heal) exist for when a person explicitly asks an agent to decide. They need the heals:review scope and the Review heals permission.