Skip to main content

​
Overview

Refrain automates browser workflows through a three-phase pipeline:
  1. Generate — AI explores your web app and builds a runbook.
  2. Execute — The runbook replays deterministically with zero AI cost.
  3. Self-heal — When UIs change, AI diagnoses failures and suggests fixes.
Each phase is independent. You generate once, execute unlimited times, and self-heal only when something breaks.

​
Phase 1: Generate

The generate command takes a URL and a goal, then lets AI explore your web app to build a runbook.
1

AI opens the browser

Navigates to the start URL and takes a snapshot of the page.
2

AI explores the page

Decides which actions to take (click, input, navigate, etc.) based on the goal and page state. Each action is recorded as a step.
3

Stall detection

If AI gets stuck in a loop or makes no progress, it asks for human guidance. You can also intervene at any time during exploration.
4

AI reviews the steps

After reaching the goal, AI reviews all recorded steps — removing unnecessary ones and flagging risky actions that may need approval.
5

Runbook output

The final runbook is written as a structured file containing all steps, selectors, variables, and settings.

​
Phase 2: Execute

The execute command replays a generated runbook. Selectors are resolved deterministically — no AI tokens are consumed on reruns (except when fallback features are triggered).
1

Load runbook and resolve variables

Variables are resolved from secrets, context, environment, or interactive prompts.
2

Execute each step

For each step, the executor resolves the selector using multi-layered resolution, then performs the action (click, input, navigate, etc.).
3

Handle approvals

Steps marked as requiring approval pause execution and wait for human confirmation via CLI, Slack, Teams, or Discord.
4

Report results

A summary is printed showing success/failure for each step, with optional screenshots and notifications.

​
Phase 3: Self-heal

When the target app’s UI changes and steps start failing, --self-heal enables AI-powered diagnostics.
1

Enhanced execution

Self-heal mode enables aggressive retry strategies, selector caching, Agent Fallback, and Vision Fallback automatically.
2

Error classification

Each failure is classified into one of 6 categories to guide the repair strategy.
3

AI repair suggestions

AI analyzes failed steps and generates two types of suggestions: runbook fixes (selector changes, step additions) and context fixes (updated page structure notes).
4

Apply fixes

Use the fix-runbook command to review and apply AI suggestions to your runbook.

​
Key design principles

  • Reproducibility — The same runbook produces the same result every time.
  • Zero rerun cost — Deterministic execution means no AI tokens on reruns.
  • Human-in-the-loop — Approval workflows keep humans in control of risky actions.
  • Self-maintaining — AI auto-maintains runbooks when UIs change.

​
What’s next

Generate a runbook

Step-by-step guide for runbook generation.

Execute a runbook

How to run your generated runbook.

Self-heal mode

Diagnose and fix broken runbooks automatically.