tranquil
Docs

Your First Automation

Time to write your own browser automation — about seven lines — and save it as a reusable command.

This is the in-app kind of automation (a .ts script you run against a browser tab). For headless workflows built with @tranquil/sdk, see the Engine (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.

1. Create the file

Create a new file anywhere in your project and name it my-first.ts. There’s no special folder — any .ts file can be an automation.

2. Write the three moves

// My first automation: count the paragraphs on the page.
// @permissions browser
import { tabs, ui } from "tranquil/automation";

const tab = await tabs.active();
const count = await tab.evaluate(() => {
  return document.querySelectorAll("p").length;
});
await ui.notify(`This page has ${count} paragraph(s).`, { level: "success" });

The () => { … } passed to evaluate runs inside the page; the rest runs in your script’s sandbox. The API all comes from the one import line.

3. Run it

  1. Open a browser tab on any page.
  2. Click back into my-first.ts so the editor is focused.
  3. Press Cmd-Shift-R (or click the ▶ Run button on the tab bar).

A notification reports the paragraph count. Change "p" to "a" or "img", select from the import line down through the changed code, and press Cmd-Shift-R to run just that selection. The output and state of every run show up in the Automation Runs panel (bottom dock).

4. Save it as a command

  1. With my-first.ts focused, run “Automations: Register Current File” from the command palette (Cmd-Shift-P).
  2. The command is named automatically from the file name — my-first.ts registers as Automations: My First.

To give a command a clearer name, name the file for what it does: count-paragraphs.ts registers as Automations: Count Paragraphs. Run it from the palette any time; it targets the active tab and persists across restarts.

Going further

  • Need more than a page can give you? Add to the header comment — // @permissions browser net=api.github.com — and Tranquil asks you to approve the change on first run. See Permissions for every grant, and Writing Automations for the full SDK and patterns like multi-page fan-out.
  • Tranquil is also growing workflows — the headless, scheduled kind that run on the Engine rather than in the app. Not yet available.

Next: Writing Automations — the full SDK reference.