Explain This Code

Overview

A Run Script node can run any shell or Python code, which is powerful but opaque if you don't read code. Explain This Code turns that script into something anyone can understand: it explains what the script does, flags whether it's safe to run, lets you ask follow-up questions, and — if you want — lets the AI rewrite the script for you and save it straight back to the node.

When you have an AI provider configured, an ✨ Explain this code button appears next to the Script field in the inspector (only when the field has content). Clicking it opens a full-canvas review: your script on the left, a plain-English explanation and a chat on the right.

The Review at a Glance

Across the top of the explanation sit three chunky tiles plus a row of capability chips:

• Safety — a color-coded verdict: green Safe, orange Caution, or red Risky.
• Language — Shell or Python, taken from the node's interpreter.
• Lines — how big the script is.
• Capability chips — shown only when relevant: Deletes files, Changes files, Needs admin, or Connects online. These tell you, concretely, what the script can reach.

Where the Safety Rating Comes From

The safety verdict is computed by a deterministic local check — a built-in scanner that looks for the canonical dangerous patterns (deleting files with rm, downloading and running code with curl | sh, requesting administrator access with sudo, wiping disks with dd or mkfs, making files world-writable with chmod 777, fork bombs, and more). It runs entirely on your Mac and never leaves your machine.

Because the check is local and instant, it re-validates on every change. If you ask the AI to add a line that deletes files, the Safety tile flips to red the moment the script updates — no waiting on the AI, and the rating can never be talked down by an overly optimistic model.

The plain-English explanation, written by your AI provider, also calls out risks in words — but the tile itself is grounded in the deterministic check. This pairs with Watchflows' broader destructive-action safeguards.

Ask Follow-up Questions

A chat is pinned to the bottom of the explanation. Ask anything about the script in plain language — “Is this safe to run on my work laptop?”, “What does line 12 do?”, “Will this change any of my files?” — and the answer streams in below the explanation.

Answers come from your configured default AI provider. The model in use is shown on a pill above the input (e.g. “Answers from … · OpenRouter”); click it to jump to AI Providers settings and change the model.

It Knows the Rest of Your Flow

The review doesn't see the script in isolation. When you open it, Watchflows hands the AI a map of how this node sits in the workflow, so it can reason about fit instead of guessing. That map includes:

• What feeds this node (the upstream steps) and what consumes its output (the downstream steps), by name and type.
• The whole wiring of the flow, plus the payload variables available to the script (the $PAYLOAD_* values) and the fact that its stdout is exposed downstream as output.

So a question like “will this work with the rest of my flow?” gets a concrete answer that names your actual trigger and downstream nodes — and a rewrite can take downstream expectations into account. If the node isn't wired to anything yet, it'll simply tell you it stands alone.

Let the AI Rewrite the Script

The chat doesn't just explain — it can edit. Ask for a change (“also log the date”, “make this simpler”, “add error handling”) and the AI rewrites the script. The new version appears live in the left pane — with an Edited marker — and is saved straight to the node, the same as if you'd typed it in the inspector.

• It can switch the language. If a task is cleaner in another language, the AI can rewrite a Bash script as native Python and flip the node's interpreter to Python 3 for you — instead of awkwardly nesting one language inside another.
• Every change is reversible. A Script updated · Undo control sits under the message that made the change. One tap restores the previous script (and interpreter).
• Safety keeps up. The Safety tile and capability chips re-evaluate against the new script immediately, so a rewrite that introduces something risky is flagged at once.

The AI only rewrites when you actually ask for a change — asking a question never alters your script.

While a review is open, the node's Script field in the inspector becomes a read-only mirror — it still reflects any rewrites as they land, but you can't hand-edit it from two places at once. Close the review to edit by hand again, or just ask the chat to make the change.

Pick Up Where You Left Off

The explanation and your whole conversation are saved per node. Reopen the review later — even after restarting the app — and your history is right there as the first messages, so you continue the conversation instead of starting over. Reopening does not re-run the review.

Conversations are stored locally on your Mac, kept out of the workflow file (they never travel with a .watchflow export), and capped so they stay small over time.

Diagnose a Failed Run

When a flow that contains your script has failed recently, the review can see it. A Diagnose button appears, and you can ask the chat “why did the recent failure happen?” — the AI reads the flow's recent run history (the failing node, its inputs, and the error) so it can point at the actual cause instead of guessing. It still never runs anything; it's reading the execution history Watchflows already recorded.

What It Doesn't Do

Explain This Code is a review-and-edit aid — it never runs the script. It only reads your script, explains it, and (when you ask) edits the node's configuration.

The script and your questions are sent only to the AI provider you've configured — which can be a fully local model (Ollama, LM Studio) if you prefer nothing leave your machine. The local safety scanner runs regardless and needs no AI at all.