Running Automations

An automation in Tranquil Studio is a small TypeScript (.ts) file that controls a browser tab. It runs in a sandboxed Deno subprocess, so it can’t touch your files or network beyond what it declares. The examples repo has several ready to run — clone it and open it as a project to follow along.

Automations vs. workflows. This page is about browser automations — scripts you run inside the desktop app against a live page. Tranquil also has workflows: @tranquil/sdk programs that run headless on a schedule or webhook. Those run on the Engine and are a separate topic (not yet available).

Dev preview — not stable. Tranquil is in early, active development. Everything here — APIs, interfaces, and behavior — is provisional and will change before a stable release, often without notice or backward compatibility. Don’t build anything you depend on against it.

The three moves

Almost every browser automation is the same shape (plus one import):

// @permissions browser
import { tabs, ui } from "tranquil/automation";

const tab = await tabs.active();                    // 1. grab the current browser tab
const n = await tab.evaluate(() => {                // 2. run code inside the page
  return document.querySelectorAll("img").length;
});
await ui.notify(`This page has ${n} image(s).`);    // 3. report back

Code inside tab.evaluate(() => { … }) runs in the web page (where document and window live). Everything outside it runs in your script.

Run one

1. Open a browser tab on any page (double-click a .url shortcut, or press Cmd-T).
2. Open an automation, e.g. page-banner/page-banner.ts, so it’s the active editor.
3. Press Cmd-Shift-R (or click the ▶ Run button on the editor’s tab bar).

page-banner.ts adds a banner to the page; run it again to remove it. Other examples read the page (page-info, count-elements), restyle it (highlight-links, reader-mode), or visit several pages at once (fetch-titles).

Watch your runs

Every run — its output, state, and duration — appears in the Automation Runs panel (bottom dock; open it with “Automations: Toggle Runs Panel”). A running script can be cancelled there, and a failed run’s notification links to its output with a real file:line stack trace.

Two things to know

• Run with the .ts editor focused, not the browser tab. The runner targets the last browser tab you viewed; from a focused browser tab, Cmd-Shift-R is the browser’s hard-reload instead. (The ▶ Run button always runs the file it’s on.)
• Put page code inside tab.evaluate(). The outer script runs in its own sandbox and can’t see the page’s document directly.

Tip: select a few lines and press Cmd-Shift-R to run only the selection — a quick way to experiment. The file’s import lines come along automatically, so you can select a single statement.

---

Next: Your First Automation — write your own.