Docs

RunMacro Documentation

Learn RunMacro from basics to advanced.

Everything you need to start and master RunMacro — from basic commands to advanced automation workflows.

Ctrl K

✨ Features

Build a web workflow with AI Web Builder

In Browser Mode, open More › Create Workflow with AI, type what you need, then press Start creating workflow. Review the plan, generate, preview, then press Add to current macro.

Prerequisites

The workspace is in Browser Mode (Chrome CDP). Desktop Mode is refused.
No macro is running and you are not recording.
An AI provider is configured in the AI / API tab with an API key — unless you use Quick Create with live observation off.
Chrome/CDP is only needed for live observation or the test run; plain workflow writing does not need it.
Because Browser Mode entry is required, this feature needs a paid license.

Supported modes

Browser Mode — Browser Mode only, and every generated workflow is pinned to browser mode. Within it there are two authoring styles: Write workflow without opening Chrome (default) and Live observation with Chrome/CDP.

What it does

AI Web Builder takes your plain-language description (optionally split into several steps), asks an AI model to generate a workflow, checks it against a fixed list of allowed commands, then converts it into real RunMacro commands inserted as a WF Group block. The AI can write straight from your text, or open Chrome and observe live — clicking, typing and scrolling to see the real page before writing.

When to use it

You want a fast draft workflow for a familiar web task.
You are unsure how to structure the flow and need a starting point to edit.
The task is easy to describe in words but slow to write command by command.
You want the AI to look at the real page before writing (enable live observation).

When not to use it

Automating desktop software — AI Web Builder supports Browser Mode only.
You need a perfectly correct workflow on the first try: always preview and test-run, or use Smart Record to capture real selectors.
The task needs commands outside the allowed list (image recognition, shell, desktop actions).

Configuration steps

Make sure you are in Browser Mode. Open More › Create Workflow with AI.
Choose the build entirely with AI card (the other one uses existing templates, which is cheaper and more accurate).
In the 1. Goal card, describe the task. Click Add step to split it into clearer steps (up to 21).
In the 2. How AI acts card, choose writing without Chrome (default) or live observation. Live observation reveals the Chrome configuration group.
In the AI settings card, pick a Builder mode: Quick Create, Plan & Build (default) or Smart Builder. Pick a Provider.
Press Start creating workflow.
For Plan & Build and Smart Builder, the AI Workflow Plan dialog opens: review blocks, variables, loops and risks. You can edit each block name and goal, or edit the plan JSON directly.
Press Generate Full Workflow, or Generate Selected Block to build one part at a time.
In the preview dialog, check the Command list and JSON tabs. Press Run test if Chrome/CDP is available.
Press Add to current macro to insert, or Create a new macro from this workflow to replace the whole macro.

Every option explained

Goal and Add step

The task description box. Click Add step to split it into ordered steps (up to 21); each is its own tab with an ✕ delete button (except step 1). The more specific the description, including the URL, the closer the result.

Write workflow without opening Chrome

The default. AI writes from your description only, without opening a browser, so it is faster and cheaper. In exchange, selectors are guesses and may need fixing at run time.

Live observation with Chrome/CDP

The AI opens or connects to Chrome and clicks, types and scrolls to see the real page before writing. More accurate but slower and it uses many more AI calls. Selecting it reveals Advanced Chrome settings for the Chrome source, profile name, size and port.

Builder mode: Quick Create

Fast and short: skips the planning step and generates directly. It is also the only mode that works with the RunMacro AI provider when live observation is off (see limitations).

Builder mode: Plan & Build

The default. The AI drafts a plan you review and edit before the workflow is generated. Best for most cases since you keep control before spending a generation.

Builder mode: Smart Builder

For complex workflows with variables, loops, conditions and error handling. It uses the most AI calls; choosing Generate Full Workflow here shows a confirmation because the estimated credit use is high.

Max actions / batch

Caps the number of actions per batch of generation or observation, not for the whole workflow. Leave it at 0 for Auto, where RunMacro picks based on builder mode and description length.

Provider

Pick the model used for generation: RunMacro AI (built-in service, no API key), ChatGPT / OpenAI, Claude / Anthropic, Gemini, DeepSeek, OpenRouter. Apart from RunMacro AI, each needs an API key in the AI / API tab.

Run test after creation (requires Chrome/CDP)

Off by default. When on, the workflow is test-run right after generation; an open Chrome/CDP is required.

Automatically create input variables from the request

On by default. The AI spots values worth turning into variables (an email, a search term) and declares them in the workflow.

The AI Workflow Plan dialog

The Summary tab shows builder mode, authoring style, estimated credits, blocks with their goals, variables, loops, conditions and risks. The Edit Plan JSON tab lets you edit the JSON directly. You can also rename and re-goal the selected block.

Preview dialog: Run test / Regenerate / Add & Continue Next Block

Run test temporarily runs the commands then restores the macro, keeping the dialog open. Regenerate rebuilds it. Add & Continue Next Block only appears when the plan has a next block: it inserts this one then generates the next, reusing the same Chrome session.

Ask AI to fix the JSON

Appears when the AI workflow is invalid. RunMacro sends the JSON back with the error list and the allowed-command list for the AI to repair. If it is still invalid, the errors refresh and you can retry or cancel.

Expected result

A WF Group block is added to your macro, containing Smart HTML/CDP commands matching your description. If the AI returns invalid JSON, an error dialog opens where you can press Ask AI to fix the JSON.

Real example

Example: open a page and search

In Browser Mode, open More › Create Workflow with AI.
Type: Go to https://example.com, type "t-shirt" in the search box, click the Search button, wait for the result list.
Leave Write workflow without opening Chrome and Plan & Build as they are. Press Start creating workflow.
Review the plan: usually one block with 4–5 actions. Press Generate Full Workflow.
In the preview, check the Command list tab to see whether the selectors look sensible.
Press Add to current macro, then run the macro to verify for real.

Example: use live observation on an unfamiliar page

Open AI Web Builder and type your description including the exact URL.
Choose Live observation with Chrome/CDP.
Expand Advanced Chrome settings, keep the Default Chrome source and 800x800 size.
Press Start creating workflow. Chrome opens and the AI works the page itself; follow along in the 4. AI progress card.
If Chrome cannot open, RunMacro offers to switch to writing without Chrome — choosing Yes still yields a draft.
Preview, press Run test, then add it to the macro.

Limitations and failure cases

The AI can only produce commands from an allowed list: navigation and tabs, web element actions, waits and assertions, basic flow control (delay, label, goto, if variable, retry), variables, and CSV/text output. There is no image recognition, desktop action, shell execution, or cross-origin iframe targeting.
The RunMacro AI provider currently only works in Quick Create with live observation off. In Plan & Build (the default) or with live observation on, the app reports a missing API key even though RunMacro AI needs none. Workaround: choose Quick Create, or pick another provider that has an API key.
The write-without-Chrome mode guesses selectors, so the workflow may need fixing at run time — the interface states this itself.
There is no cancel button while the AI is working: pressing Cancel only closes the dialog, and the AI call continues in the background.
There are reports of one click on Add to current macro inserting two near-identical groups. After adding, check the command list and delete the duplicate group if you see one.
There are reports of the app closing unexpectedly when dismissing the preview after adding. The preview now closes itself after a successful add to avoid that path.
Some labels in the plan and preview dialogs remain in English while the interface is set to Vietnamese.
Unsupported steps that slip past validation are silently dropped during conversion — fewer commands than the plan suggested is a sign of this.

Tips & common mistakes

Include the full URL in your description. A missing URL is the most common reason the AI drifts off target.

Use Generate Selected Block for long tasks: generating and checking piece by piece is easier to fix than one large workflow.

Always preview and test-run before trusting an AI-written workflow. A wrong selector guess can click the wrong thing on the real page.

The build from existing templates card is cheaper and more accurate for familiar tasks — consider it before having AI write from scratch.

When you need selectors that are certainly right, use Smart Record: it captures real selectors from the page instead of letting AI guess.

Verification details

ui/ai_web_builder_dialog.py
core/ai_web_builder.py
core/ai_workflow_capabilities.py