libretto
Health Warn
- No license — Repository has no license file
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 36 GitHub stars
Code Warn
- process.env — Environment variable access in .github/workflows/evals.yml
- fs module — File system access in .github/workflows/evals.yml
- process.env — Environment variable access in .github/workflows/opencode-review.yml
Permissions Pass
- Permissions — No dangerous permissions requested
This toolkit provides an AI-driven live browser and CLI environment for developers to build, inspect, and debug web automations. It allows agents to record user actions, inspect live pages, and capture network traffic to reverse-engineer APIs.
Security Assessment
The tool inherently makes network requests and accesses the local file system to manage browser automations and configurations. During installation, the setup process checks for environment variables (like `OPENAI_API_KEY`) to automatically configure AI provider credentials, storing them locally in a config file. The codebase scan shows environment variable and file system access limited strictly to automated GitHub workflow files, rather than the core source code. There are no hardcoded secrets detected, and the tool does not request inherently dangerous permissions. Because it actively handles live browser sessions, captures network traffic, and manages API keys, the overall risk is rated as Medium.
Quality Assessment
The project appears actively maintained, with its most recent code push occurring today. It has a solid foundation of community trust with 36 GitHub stars. However, there is a discrepancy in licensing: while the automated rule-based scan warned about a missing license file in the repository, the README explicitly displays an MIT license badge. This likely means the license simply exists in a non-standard location or is applied at the package level rather than the root directory.
Verdict
Use with caution: the tool is actively maintained and open-source, but its access to live browser data and local API keys requires standard security diligence.
The AI toolkit for building and maintaining browser automations
Libretto
Libretto is a toolkit for building robust web integrations. It gives your coding agent a live browser and a token-efficient CLI to:
- Inspect live pages with minimal context overhead
- Capture network traffic to reverse-engineer site APIs
- Record user actions and replay them as automation scripts
- Debug broken workflows interactively against the real site
We at Saffron Health built Libretto to help us maintain our browser integrations to common healthcare software. We're open-sourcing it so other teams have an easier time doing the same thing.
https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18
Installation
npm install libretto
# First-time onboarding: install skill, download Chromium, and pin the default snapshot model
npx libretto setup
# Check workspace readiness at any time
npx libretto status
# Manually change the snapshot analysis model (advanced override)
npx libretto ai configure <openai | anthropic | gemini | vertex>
setup detects available provider credentials (e.g. OPENAI_API_KEY) and automatically pins the default model to .libretto/config.json. Re-running setup on a healthy workspace shows the current configuration instead of re-prompting. If credentials are missing for a previously configured provider, setup offers an interactive repair flow.
Use ai configure when you want to explicitly switch providers or set a custom model string.
Use cases
Libretto is designed to be used as a skill through your coding agent. Here are some example prompts:
One-shot script generation
Use the Libretto skill. Go on LinkedIn and scrape the first 10 posts for content, who posted it, the number of reactions, the first 25 comments, and the first 25 reposts.
Your coding agent will open a window for you to log into LinkedIn, and then automatically start exploring.
Interactive script building
I'm gonna show you a workflow in the eclinicalworks EHR to get a patient's primary insurance ID. Use libretto skill to turn it into a playwright script that takes patient name and dob as input to get back the insurance ID. URL is ...
Libretto can read your actions you perform in the browser, so you can perform a workflow, then ask it to use your actions to rebuild the workflow.
Convert browser automation to network requests
We have a browser script at ./integration.ts that automates going to Hacker News and getting the first 10 posts. Convert it to direct network scripts instead. Use the Libretto skill.
Libretto can read network requests from the browser, which it can use to reverse engineer the API and create a script that directly calls those requests. Directly making API calls is faster, and more reliable, than UI automation. You can also ask Libretto to conduct a security analysis which analyzes the requests for common security cookies, so you can understand whether a network request approach will be safe.
Fix broken integrations
We have a browser script at ./integration.ts that is supposed to go to Availity and perform an eligibility check for a patient. But I'm getting a broken selector error when I run it. Fix it. Use the Libretto skill.
Agents can use Libretto to reproduce the failure, pause the workflow at any point, inspect the live page, and fix issues, all autonomously.
CLI usage
You can also use Libretto directly from the command line. All commands accept --session <name> to target a specific session.
npx libretto setup # interactive first-run onboarding; run yourself, not through an agent
npx libretto status # check AI config health and open sessions
npx libretto open <url> # launch browser and open a URL (headed by default)
npx libretto snapshot --objective "..." --context "..." # capture PNG + HTML and analyze with an LLM
npx libretto exec "<code>" # execute Playwright TypeScript against the open page (single quoted argument)
echo "<code>" | npx libretto exec - # intentionally read Playwright TypeScript from stdin
npx libretto run <file> # run the file's default-exported workflow
npx libretto resume # resume a paused workflow
npx libretto pages # list open pages in the session
npx libretto save <domain> # save browser session (cookies, localStorage) for reuse
npx libretto close # close the browser
npx libretto ai configure <provider> # manually change snapshot analysis model
npx libretto status # show AI config and open sessions
Configuration
All Libretto state lives in a .libretto/ directory at your project root. Configuration is stored in .libretto/config.json.
Config file
.libretto/config.json controls snapshot analysis and viewport settings:
{
"version": 1,
"ai": {
"model": "openai/gpt-5.4",
"updatedAt": "2026-01-01T00:00:00.000Z"
},
"viewport": { "width": 1280, "height": 800 }
}
The ai field configures which model Libretto uses for snapshot analysis — extracting selectors, identifying interactive elements, or diagnosing why a step failed. This keeps heavy visual context out of your coding agent's context window. Snapshot analysis is required.
npx libretto setup automatically pins the default model for the first provider whose credentials it finds. To explicitly change the provider or model afterward:
npx libretto ai configure <openai | anthropic | gemini | vertex>
To inspect the current configuration without changing anything:
npx libretto status
Provider credentials are read from environment variables or a .env file at your project root: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY, or GOOGLE_CLOUD_PROJECT for Vertex.
The viewport field sets the default browser viewport size. Both fields are optional.
Sessions
Each Libretto session gets its own directory under .libretto/sessions/<name>/ containing runtime state. Sessions are git-ignored.
state.json— session metadata (debug port, PID, status)logs.jsonl— structured session logsnetwork.jsonl— captured network requestsactions.jsonl— recorded user actionssnapshots/— screenshot PNGs and HTML snapshots
Profiles
Profiles save browser sessions (cookies, localStorage) so you can reuse authenticated state across runs. They are stored in .libretto/profiles/<domain>.json, created via npx libretto save <domain>. Profiles are machine-local and git-ignored.
Community
Have a question, idea, or want to share what you've built? Join the conversation on GitHub Discussions.
- Q&A — Ask questions and get help
- Ideas — Suggest new features or improvements
- Show and tell — Share your workflows and automations
- General — Chat about anything Libretto-related
Found a bug? Please open an issue.
Authors
Maintained by the team at Saffron Health.
Development
For local development in this repository:
pnpm i
pnpm build
pnpm type-check
pnpm test
Source layout:
packages/libretto/src/cli/— CLI commandspackages/libretto/src/runtime/— browser runtime (network, recovery, downloads, extraction)packages/libretto/src/shared/— shared utilities (config, LLM client, logging, state)packages/libretto/test/— test files (*.spec.ts)packages/libretto/README.template.md— source of truth for the repo and package READMEspackages/libretto/skills/libretto/— source of truth for the Libretto skill
Run pnpm sync:mirrors after editing packages/libretto/README.template.md or anything under packages/libretto/skills/libretto/.
To check that generated READMEs, skill mirrors, and skill version metadata are in sync without fixing them, run pnpm check:mirrors. To release, run pnpm prepare-release.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found