---
id: saffron-health/libretto/libretto-readonly
version: "55b2ad79"
license: MIT
install: manual
updated: 2026-07-27
---

# libretto-readonly — libretto-readonly lets you examine and diagnose the current state of any live browser session without altering the page or application. Built as part of Saffron Health's AI automation toolkit, it provides reliable inspection capabilities for debugging and understanding browser behavior in real time.

Publisher: saffron-health · Stars: 841 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/saffron-health/libretto`

## SKILL.md

## How Libretto Read-Only Works

- Use this skill when the browser session must stay strictly read-only.
- Libretto stores read-only vs write-access on the session itself.
- The primary inspection tools are `snapshot` and `readonly-exec`.
- `readonly-exec` reuses Libretto's normal execution pipeline, but it only exposes read-only helpers and denies mutating Playwright methods.
- Only a user can change the session mode for an existing session. Never change a session's mode on your own — the user must change it themselves manually.

## Working Rules

- Announce which session you are using and what page you are inspecting.
- Do not use `exec`, `run`, or any direct Playwright action that could change browser or application state.
- Do not click, type, submit forms, navigate, upload files, dispatch DOM events, or send non-GET requests.
- Prefer `snapshot` first when the visible page state is unclear.
- Use `readonly-exec` for focused inspection: titles, HTML, locator text, counts, visibility checks, and GET requests.
- Keep snippets small and purpose-built. Do not run multiple `readonly-exec` commands at the same time.
- Close disposable sessions before your final response once inspection is complete. Open browsers keep consuming local or hosted resources.
- End with diagnosis and handoff guidance, not an attempted in-browser repair.

## Commands

### `connect`

- Use `connect` to attach to an existing CDP endpoint for a preserved browser session.
- Use `--read-only` when creating the Libretto session handle for a preserved browser session.
- Libretto read-only mode is enforced through Libretto commands; direct CDP clients that skip Libretto are outside this boundary.

```bash
libretto connect http://127.0.0.1:9222 --read-only --session failed-job-debug
```

### `pages`

- Use `pages` when a popup, new tab, or second page exists.
- If `readonly-exec` or `snapshot` complains about multiple pages, list ids first and then pass `--page`.

```bash
libretto pages --session failed-job-debug
```

### `snapshot`

- Use `snapshot` as the first high-level observation tool.
- Run `snapshot <ref>` to inspect a subtree from the latest full snapshot.

### `readonly-exec`

- Use `readonly-exec` for narrow inspection code only.
- Denied operations fail with `ReadonlyExecDenied: ...`.

#### Helpers

- `page` — a read-only Playwright `Page` proxy. Standard Playwright read methods work normally (`url()`, `title()`, `content()`, `getByRole()`, `locator()`, `textContent()`, `isVisible()`, `count()`, `scrollIntoViewIfNeeded()`, etc.). Anything that mutates the page (`click`, `fill`, `goto`, `evaluate`, `keyboard`, `mouse`) is blocked.
- `state` — the current Libretto session state object.
- `get(url, options?)` — HTTP client restricted to **GET and HEAD** requests. Replaces `fetch`, which is blocked in readonly mode. Any request with a body or a non-GET/HEAD method throws `ReadonlyExecDenied`.
- `scrollBy(deltaX, deltaY)` — scroll the viewport by pixel offset. Use this to inspect content below the fold without targeting a specific element.

Standard JS globals `console`, `URL`, `Buffer`, `setTimeout`, and `setInterval` are also available.

#### Examples

```bash
libretto readonly-exec "return page.url()" --session failed-job-debug
libretto readonly-exec "return await page.getByRole('heading').first().textContent()" --session failed-job-debug

# HTTP GET inspection
echo "const r = await get('https://api.example.com/status'); return await r.json()" \
  | libretto readonly-exec - --session failed-job-debug

# Scroll down to inspect below-the-fold content
libretto readonly-exec "await scrollBy(0, 500)" --session failed-job-debug
```

### `close`

- Use `close` when the inspection session is no longer needed, unless the user explicitly asks to keep the browser open.

```bash
libretto close --session failed-job-debug
```


[View on SkillFed](https://skillfed.io/saffron-health/libretto/libretto-readonly) · [View on GitHub](https://github.com/saffron-health/libretto)