Use AI Assistant to ask, diagnose, and review workflow changes

Prerequisites

• RunMacro Studio must be open for the full conversation surface; Runner requires a log or error context and enters through diagnosis.
• The PC needs connectivity to the RunMacro AI service, and the live status response must mark Assistant available.
• An active Trial or Pro licence is required when the service reports that entitlement; remaining credit comes from live status rather than this guide.
• For a correctly targeted patch, open the affected macro and select the intended row or contiguous range before sending.
• The Image picker is enabled only when live status allows image input; pasted/dropped images and an opted-in failure screenshot still undergo their own format and size checks and are not gated by this flag.

Supported modes

• Desktop Mode — Studio exposes the full right-side Assistant panel in Desktop Mode: chat, history, scope, context, attachments, and change review. The request records Desktop mode, but Assistant does not execute screen actions to verify its answer.
• Browser Mode — Studio provides the same full panel in Browser Mode and labels the request as Browser. Browser state, DOM, and screenshots remain off by default and require separate confirmation; Assistant does not replace Smart Record or observe a page without approved evidence.
• QMacro Runner — QMacro Runner opens Assistant only from its log/error-diagnosis flow and requires nonempty logs or error context, not necessarily a newly failed run. The request is prefilled but never auto-sent; proposals are summary-only because Runner has neither the Studio Apply API nor a workflow editor.

What it does

AI Assistant is a conversational panel integrated with RunMacro Studio. It explains features, answers workflow questions, analyzes approved run evidence, and, only when a response contains a valid structured proposal, shows a change summary so you can choose Apply or Cancel. Each request uses the RunMacro-hosted AI service and carries the active mode, the user prompt, up to ten recent chat messages, and only context sections you enabled. A macro_patch is checked against fingerprints and scope when received; Apply reruns patch, fingerprint, command, and analyzer validation but not the separate scope-membership check, then creates one undoable editor transaction. Ordinary chat never edits or builds a workflow by itself. QMacro Runner opens Assistant only from a log/error flow with available context and has no full Studio editing surface.

When to use it

• Use it to explain a RunMacro command, mode, or behavior in the context of the workflow currently open in Studio.
• Use it to analyze logs, error evidence, a run report, or an image or file that you deliberately attach.
• Use it to request a small change to one command, a selected range, a containing block, or the whole workflow, read the summary, and deliberately Apply or Cancel.
• Use it after a failed run when a prefilled diagnosis request is useful but you still want to review consent and context before sending.

When not to use it

• Do not use it instead of AI Web Builder when the primary goal is the dedicated structured flow for generating a new workflow from scratch.
• Do not use it instead of Smart Record when you need to capture real page interactions and selectors from a live Browser session.
• Do not send a request when data must remain entirely on the PC; disable unnecessary context and do not attach sensitive files.
• Do not treat an answer or patch as tested output; read the summary, apply deliberately, rerun the affected workflow, and Undo if it is wrong.

Configuration steps

1. In Studio, click Assistant at the right edge of the toolbar, choose RunMacro Assistant from More, or use the Create with AI empty-workflow card. After a failure, Diagnose this run or the fix action opens the same panel with a prompt prefilled but never auto-sent.
2. Choose the scope before typing: Selected command, Selected range, Containing block, or Whole workflow. An empty workflow offers only New workflow.
3. Open Data AI can view. Fresh defaults include Workflow/selection and Variable names; enable Logs, Error evidence, Run report, or sensitive sections only when the question requires them.
4. When enabling Command values, Variable values, Current data row, Browser, DOM, or Screenshot, read the confirmation and approve only if sending that material is acceptable. Prompt text cannot turn on a disabled permission.
5. If useful, open the plus menu and add an Image, the current Log, a Data file, or a PMacro/workflow. Review every card, the visible count, and the X remove action.
6. Write the question or requested change. Select Preview data sent to AI to inspect the outbound payload, binary-image count, and up to ten recent messages included with the request.
7. Click the arrow send button or press Enter; use Shift+Enter for a new line. Wait for the answer and inspect live credit or service status if sending is disabled or the service reports an outage.
8. For a normal answer, verify the guidance yourself. For a Suggested macro patch or Suggested change, read the operation and row summary carefully before deciding.
9. Choose Apply only when scope and contents are correct, then rerun affected branches. Use Undo for the just-applied transaction, or Cancel to discard the proposal without editing the workflow.

Every option explained

Expected result

You receive an answer grounded in the active mode and approved context, while the conversation is stored locally for later reopening. A valid server macro_patch produces a card with operation and row counts; Apply creates one editor transaction, marks the macro dirty, and shows an Undo action that stays within the panel width. Cancel discards the proposal. Chat-only or invalid proposals leave the workflow unchanged. Diagnosis from Studio or Runner remains prefilled until you explicitly send it.

Real example

Limitations and failure cases

• Assistant uses the hosted RunMacro AI service and requires connectivity; this panel has no local or offline chat mode.
• The Assistant UI exposes no provider, model, base URL, or API-key selector. The service controls upstream selection; the client only bounds error text and does not guarantee that hosted responses suppress every provider or model detail.
• Entitlement, image capability, and quota come from live status; this guide promises no fixed price, credit amount, or limit.
• An ordinary chat response never edits the workflow. Apply appears only for a valid macro_patch or legacy workflow_draft when the host supports editing.
• Assistant does not always create or edit workflows; a request may produce an explanation, service failure, invalid proposal, or no structured proposal at all.
• Redaction uses allowlists, key names, and patterns to reduce exposure; it does not guarantee anonymity and can leave PII, URLs, business text, or sensitive values under ordinary names.
• Enabling Command values, Variable values, Current data row, Browser, DOM, or Screenshot can transmit personal or secret information. Confirmation records consent but does not make the data harmless.
• Context JSON is capped at about 9,000 characters; the roughly 11,500-character budget applies to optional context and attachment text after the prefix and user request, while the prompt has no enforced cap and binary images are separate. Workflow details allow 60 commands, the catalog 20 types, and logs 80 lines or 6,000 characters; long evidence is compacted.
• Only the ten most recent chat messages accompany a request. Local history may be longer, but the full archive is not sent each time.
• Direct log/text/PMacro attachments are sent as bounded excerpts, so a truncated tail can omit relevant evidence; sources over 512 KiB or a 2 MiB combined direct total are rejected. The separate Data file flow accepts sources up to 20 MiB before attaching bounded schema/sample JSON, while protected QMacro is rejected.
• Images can be resized or re-encoded, and animation is unsupported. A failure screenshot uploads only after separate opt-in and only within the three-image and combined-byte limits.
• Fingerprints block a patch when targets changed or fall outside approved scope, but they do not establish business correctness. A stale patch is rejected rather than rebased automatically.
• Patches support only four defined operations, cannot use update_fields to change type or ID, reject unknown or removed commands, and cannot introduce a new analyzer error.
• Undo is offered for the just-applied Assistant transaction and can be used once; later editor work still follows normal save and undo behavior.
• Legacy workflow_draft uses the validator-approved capability set and appends a command group at the end. Unsupported step types are rejected before the importer runs. The card shows only a summary, so rerun after Apply and use Undo if conversion is not what you intended.
• Runner has a log/error-diagnosis dialog only, requires nonempty log or error context, and cannot apply patches or drafts. When context points to another macro, that macro must be opened before generating an applicable fix.
• Chat history and managed images are stored locally; text-attachment metadata is retained but excerpts are not. Deleting a conversation cannot retract data already sent to the service.
• Change Provider opens AI/API settings for configured-provider features; it neither changes the hosted Assistant model nor resends a quota-exhausted request.
• In-app AI Assistant is distinct from AI Web Builder, Smart Record, and AI Integration. These app entry points are separate; sharing behavior with website Support Chat is outside this guide’s evidence. Support Chat handles public product or purchase questions without the desktop workflow or runtime context described here.

Tips & common mistakes

Verification details

• ui/main_window.py
• ui/runmacro_assistant_dialog.py
• ui/qmacro_runner_window.py
• core/runmacro_ai_client.py
• core/assistant_context.py
• core/runmacro_ai_images.py
• core/macro_patch.py
• core/ai_workflow_importer.py
• core/settings.py
• tests/test_runmacro_assistant_dialog.py
• tests/test_runmacro_assistant_context.py
• tests/test_runmacro_ai_client.py
• tests/test_runmacro_ai_images.py
• tests/test_assistant_scope.py
• tests/test_macro_patch.py
• tests/test_assistant_main_window_integration.py

Related commands