Windmill Preview Workflow

Use this skill any time the user wants to see, open, navigate to, visualize, or preview a flow, script, or app — and any time you've just finished writing one and want to offer visual verification.

The Windmill dev page renders the flow graph / script editor, lets the user step through steps, and live-reloads on every save. It runs locally via wmill dev and is reached on a localhost port.

Two independent decisions

1. Mode: proxy or direct?

wmill dev runs in two modes; pick by asking what kind of URL whatever will display the preview needs.

• Proxy (--proxy-port <port>) — exposes the dev page on http://localhost:<port>/. Use it when the embedder you'll hand the URL to only accepts localhost URLs (most in-IDE / in-chat preview embedders do, because they sandbox cross-origin loads).
• Direct (default) — the user's browser loads the dev page from the remote workspace's HTTPS URL; the local wmill dev only runs the WebSocket back-channel for live reload. Use it when the URL will be opened in a regular browser tab.

Default to direct unless you have a specific embedder that needs localhost.

2. Who starts the server?

• You start it in the background. Spawn wmill dev … (or wmill app dev …) yourself, capture the URL it prints, do whatever's next (open a tab, hand the URL to an embedder).
• The runtime starts it from .claude/launch.json. Some runtimes (currently the Claude Desktop / Claude Code MCP preview integration — tools prefixed with mcp__Claude_Preview__) can read a launch.json configuration and launch the dev server on demand when you invoke their preview tool. Only take this path if you actually have such a tool — otherwise nothing reads the file and wmill dev never starts.

The two decisions compose. The common cases:

Embedder	Needs localhost?	launch.json runtime?	What to do
Regular browser tab	No	n/a	Direct mode, you start it, give URL to user
IDE / chat preview pane that takes any URL	No	No	Direct mode, you start it, point the embedder at the printed URL
IDE / chat preview pane that only accepts localhost	Yes	No	Proxy mode, you start it, point the embedder at http://localhost:<port>/
Claude Desktop / Code MCP preview	Yes	Yes	Proxy mode, write a launch.json entry, invoke the MCP tool

Never start the proxy "just in case" — it adds the localhost hop for no benefit when no embedder needs it.

Starting the server yourself

Use this when no launch.json-aware runtime is available, regardless of mode.

For flows / scripts:

# Direct mode — gives you the remote dev-page URL
wmill dev --path <wmill_path> --no-open

# Proxy mode — gives you a localhost URL that 302s to the remote dev page
wmill dev --proxy-port 4000 --path <wmill_path> --no-open

For apps:

cd <app_path>__raw_app && wmill app dev --no-open --port 4000

Each command prints the URL on stdout. Line shapes differ:

• wmill dev --no-open (direct) prints Go to <url> with the full remote URL (workspace, token, path baked in).
• wmill dev --proxy-port prints Dev proxy listening on http://localhost:<port> — the URL to hand to an embedder is http://localhost:<port>/.
• wmill app dev --no-open prints 🚀 Dev server running at <url> — the local app server.

Capture the URL with a loose match (the first https?://… token after startup) and either hand it to your embedder or relay it to the user: "Preview is running — open <url> in your browser." Don't construct the URL yourself; you don't have the workspace ID or auth token.

These commands are long-running — start them in the background, don't block waiting.

Letting launch.json start the server (Claude Desktop / Code MCP only)

Take this path when and only when an mcp__Claude_Preview__* MCP tool is exposed in your tool list. Skip it otherwise — without an MCP tool reading the file, wmill dev never starts.

Each flow / script / app gets its own named entry in the user's .claude/launch.json so multiple previews coexist without colliding — each entry pins a different port + path. Never reuse a generic "windmill" entry for different targets.

Step 1 — Reuse or add a per-target entry in .claude/launch.json

Convention: name the entry windmill: <wmill_path> (e.g. windmill: f/test/my_flow).

• Entry already exists → reuse it; note its port for the next step.
• Not there → add one. Pick a port not already taken by another entry (start at 4000 and bump). Shape:

For flows / scripts:

{
  "name": "windmill: f/test/my_flow",
  "runtimeExecutable": "bash",
  "runtimeArgs": ["-c", "wmill dev --proxy-port ${PORT:-4000} --path f/test/my_flow --no-open"],
  "port": 4000,
  "autoPort": true
}

For apps (*__raw_app/), wmill app dev is the equivalent — runs from the app folder, no --path:

{
  "name": "windmill: f/test/my_app",
  "runtimeExecutable": "bash",
  "runtimeArgs": ["-c", "cd f/test/my_app__raw_app && wmill app dev --no-open --port ${PORT:-4001}"],
  "port": 4001,
  "autoPort": true
}

If .claude/launch.json doesn't exist yet, create it with the standard shell { "version": "0.0.1", "configurations": [...] }.

Step 2 — Invoke the MCP preview tool

Point it at the entry you just added/found. Use http://localhost:<port>/ as the URL — the proxy's redirect at / is what appends the workspace ID, the auth token, and the path. Do NOT construct a /dev?... URL yourself.

The MCP tool launches the configuration on demand, so you don't need to start the wmill dev process manually.

Non-visual alternative

If the user wants a programmatic test rather than a visual one:

• Flow: wmill flow preview <path> -d '<args>'
• Script: wmill script preview <path> -d '<args>'

Both print the job result, are safe to run yourself, and don't deploy.

Anti-patterns to avoid

• ❌ Writing a .claude/launch.json entry when no mcp__Claude_Preview__* tool is in your tool list. Nothing will read the file; the server never starts. Spawn wmill dev yourself instead.
• ❌ Starting the proxy when no embedder needs a localhost URL. Direct mode is the right choice — the proxy is overhead with no purpose.
• ❌ Reusing a single generic launch.json entry for every preview target. Each flow/script/app gets its own named entry on its own port — that's how multiple sessions coexist without one preview clobbering another.
• ❌ Mutating an existing entry's --path to retarget it. Add a new entry instead.
• ❌ Constructing http://localhost:<port>/dev?path=<X> yourself. The proxy's / redirect is what appends the workspace ID and auth token; bypassing it gives a broken page. Always use http://localhost:<port>/.
• ❌ Starting wmill dev in the foreground (you'll hang). Always background.
• ❌ Listing both "open in IDE pane" and "open in browser" as a menu — pick one based on context.