tranquil
Docs

Quick Start

Open a web app, write a browser automation in about seven lines, and save it as a reusable command. You’ll need Tranquil Studio running first: see Local Dev Setup.

1. Open a web app

  • Cmd-T opens a new browser tab, split into a pane beside the editor.
  • Type an address in the URL bar and press Enter. Not a URL? It runs a search.

Any page works for this walkthrough. Leave the tab open.

2. 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.

3. 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.

4. Run it

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

The first run asks you to approve the permissions the script declares: browser, because it reads the active page. Approve once and it’s remembered for that script.

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).

5. 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.