Skip to main content
Libretto is a toolkit for building robust web integrations. It gives your coding agent a live browser and a token-efficient CLI to inspect pages, capture traffic, record actions, and debug workflows — all without flooding your agent’s context window with raw HTML. Built by the team at Saffron Health, Libretto was created to help maintain browser integrations to common healthcare software. It’s open-source so other teams can do the same.

​
Core capabilities

Libretto is organized around four capabilities that cover the full lifecycle of a browser automation: Inspect live pages — Take a snapshot of any open page and let a vision model extract selectors, identify interactive elements, and summarize the visible state. Snapshot analysis runs in a separate process so the results are token-efficient summaries, not raw DOM dumps. Capture network traffic — Record every HTTP request and response made by the browser. Libretto writes these to a structured JSONL log you can query with jq or pass directly to your agent to reverse-engineer the site’s API. Record user actions — As you interact with a page manually, Libretto captures each DOM event with a semantic selector, nearby text, and coordinates. Your agent can read these recorded actions and reconstruct the workflow as a typed Playwright script. Debug broken workflows — When a workflow fails, Libretto keeps the browser open. Your agent can inspect the live page state with snapshot and exec, identify the broken selector or unexpected page change, patch the code, and re-run — all without restarting from scratch.

​
The skill concept

Libretto is designed to be loaded as a skill in your coding agent. A skill is a set of instructions that tells your agent when and how to use a tool. When you give your agent the Libretto skill, it knows to:
  • Open a browser before guessing at page structure
  • Use snapshot as the primary observation tool instead of reading raw HTML
  • Prefer network request approaches over UI automation when the site allows it
  • Validate a finished workflow with a headless run before declaring it done
The skill file ships with the package at skills/libretto/SKILL.md and is automatically copied into .agents/skills/libretto and .claude/skills/libretto when you run npx libretto init. You can invoke Libretto skills with natural language prompts like:
Use the Libretto skill. Go to LinkedIn and scrape the first 10 posts — content, author, reaction count, and first 25 comments.
I’ll show you a workflow in eClinicalWorks to get a patient’s primary insurance ID. Use the Libretto skill to turn it into a Playwright script.
We have a browser script at ./integration.ts that’s throwing a broken selector error. Fix it. Use the Libretto skill.

​
Architecture overview

​
CLI vs Library API

Libretto ships two interfaces:
  • CLI (npx libretto <command>) — the primary interface for both agents and humans. Commands open browsers, take snapshots, execute Playwright code, run workflow files, and manage sessions. Every command accepts --session <name> to target a specific browser session.
  • Library API (import { workflow } from "libretto") — used inside workflow files you want to run with npx libretto run. The workflow() function wraps your automation handler and gives it typed access to page, session, logger, and optional application services.

​
Sessions

A session is a named browser context. When you run npx libretto open https://example.com --session my-session, Libretto launches a Chromium instance and registers it under that name. Subsequent commands (snapshot, exec, network, actions) all target that session by name. If you don’t pass --session, Libretto uses a default session name. Sessions are independent — you can have multiple sessions open at the same time, each pointing to a different browser or URL.

​
The .libretto/ directory

All Libretto state lives in a .libretto/ directory at your project root: 
.libretto/
├── config.json          # AI model and viewport settings
├── sessions/
│   └── <name>/
│       ├── state.json   # Debug port, PID, status
│       ├── logs.jsonl   # Structured session logs
│       ├── network.jsonl
│       ├── actions.jsonl
│       └── snapshots/   # PNG + HTML captures
└── profiles/
    └── <domain>.json    # Saved auth state
Sessions and profiles are automatically git-ignored by a .libretto/.gitignore file that npx libretto init creates.

​
Next steps

Quick start

Install Libretto and run your first browser automation in minutes.

CLI reference

Full reference for every Libretto command and flag.

Library API

Write workflow files with the typed workflow() API.

Guides

End-to-end walkthroughs: scraping, network capture, debugging.

Build docs developers (and LLMs) love

Get started for freeTalk to us