# lightpanda

Adopt this skill: https://proskills.md/skills/other/lightpanda-io-agent-skill

Page: https://proskills.md/skills/other/lightpanda-io-agent-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: pandascript/SKILL.md
size: 15504
sha: 7a0b8e554376c8f56fd410051525866f82c87668
upstream: https://github.com/lightpanda-io/agent-skill/blob/HEAD/pandascript/SKILL.md

````text
---
name: pandascript
description: Write PandaScript agent scripts (.js) — Lightpanda's replayable browser-automation format, run token-free with `lightpanda run script.js`.
---

# Writing Lightpanda agent scripts

Run with:

```console
./lightpanda run script.js
```

## Mental model (get this right first)

The script runs in its **own V8 context** — neither the page nor Node.js:

- `Page` is the only global. `new Page()` makes a page and `await page.goto(url)` navigates it; every other primitive is a **method on that page**: `const page = new Page(); await page.goto(url); page.extract({...}); page.click(sel);`.
- No `window`, `document`, DOM, `localStorage` — read pages with `page.extract(...)`, run page-side JS only via `page.evaluate("...")`.
- No `require`, `process`, `fs`, npm. Standard ECMAScript built-ins only (`JSON`, `Map`, template literals, …).
- `page.goto(...)` is **async — always `await` it**. Page methods are **synchronous**: `const data = page.extract({...})`, never `await page.extract(...)`. The script body runs as an async function, so top-level `await` is allowed.
- **Re-navigating reuses the same page**: `await page.goto(url2)` keeps `page` valid and points it at the new URL, discarding the old page — read it before navigating away. Independent URLs don't share a page: make a `new Page()` for each and load them in parallel (fan-out, best practice 2).
- Page `evaluate("...")` cannot see script variables — interpolate values into the string. Script code cannot see page variables.
- Variables persist across navigations within one run, so cross-page aggregation is plain JS.
- **`return <value>` is the script's output**, printed automatically (objects/arrays as JSON). End with `return page.extract({...});` or `return results;`. A bare trailing expression is NOT printed; neither is `console.log(JSON.stringify(...))`.

## Primitives

`Page` is the only global; `new Page()` makes a page and everything else is a method on it.

| Call | Notes |
|------|-------|
| `new Page()` | Makes a page object. No navigation yet — call `page.goto(url)` before any other method. Make several to navigate in parallel (fan-out, best practice 2). |
| `page.close()` | Marks the page done; later method calls on it error. The page is otherwise reclaimed at script end. |
| `await page.goto(url[, { timeout, waitUntil }])` | **Async — must be `await`ed.** Navigates the page (re-navigating reuses the same object). Waits for `load`. Rejects on navigation failure; a **timeout does NOT reject** (the page may still be usable). Default timeout 10000 ms. `waitUntil`: one of `"load"`, `"domcontentloaded"`, `"networkalmostidle"`, `"networkidle"`, `"done"`. |
| `page.screenshot([{ path, selector, fullPage, strip, url, timeout }])` | `path` is required: writes a PNG of the text layout. |
| `page.evaluate(script[, { url, timeout, save }])` | Page-side JS escape hatch; returns text (JSON for objects/arrays). |
| `page.extract(schema)` | The only primitive returning a real JS value (object/array). The schema is its only argument. See schema below. |
| `page.click(selector)` |  |
| `page.fill(selector, value)` |  |
| `page.scroll([{ selector, x, y }])` |  |
| `page.waitForSelector(selector[, { timeout }])` | `waitFor*` default timeout 5000 ms. |
| `page.waitForScript(script[, { timeout }])` | Re-evaluates page JS until truthy. |
| `page.waitForState(state[, { timeout }])` | `state`: one of `"load"`, `"domcontentloaded"`, `"networkalmostidle"`, `"networkidle"`, `"done"`. |
| `page.hover(selector)` |  |
| `page.press(selector, key)` | Selector first! `page.press("Enter")` binds "Enter" to `selector` and fails — use `page.press(null, "Enter")` or `page.press({ key: "Enter" })`. |
| `page.selectOption(selector, value)` |  |
| `page.setChecked(selector[, checked])` | `checked` defaults to `true`. |
| `page.download([{ url, path }])` | Sends the session's cookies, so authenticated downloads work. Nothing is written unless the status is 200-203, and a failed download leaves `path` as it was. |
| `page.callPageTool([{ name, arguments }])` | Runs a tool the page registered through WebMCP; returns its text result. |
| `page.classify(questions[, { selector, presets }])` | Classifies page state or candidate elements via TypeSafe Jev: an array of categories, or an object of presets and questions. Replay calls Jev live and needs `TYPESAFE_API_KEY`. |
| `page.acceptCookies([{ prefer, selectors }])` | Clicks the consent control Jev picks, then re-reads the page to check the banner went. Pass the `selectors` from an earlier result to click them with no model call; otherwise needs `TYPESAFE_API_KEY`. `prefer`: one of `"accept"`, `"reject"`. |
| `page.login([{ password, username, usernameSelector, passwordSelector, submitSelector, nextSelector, decideOnly }])` | Fills the sign-in fields Jev picks and submits. Credentials go in as `$LP_*` placeholders. Pass the `*Selector` fields from an earlier result to replay with no model call; otherwise needs `TYPESAFE_API_KEY`. |

Options (the trailing `{ … }` object; every option may be omitted):

- `goto`: `timeout` — Optional timeout in milliseconds. Defaults to 10000. `waitUntil` — Event that completes the navigation. Defaults to 'load'. Prefer 'domcontentloaded' followed by waitForSelector on pages whose late scripts (ads) hold 'load' back. Avoid 'done' (full quiescence): on pages with constant background activity it is the slowest choice and can run to the timeout.
- `screenshot`: `path` — Optional relative path (no '..' segments) to write the PNG to. Created or overwritten. Without it the image is returned inline, which needs a client that can display images. `selector` — Optional CSS selector. When set, render only that element. `fullPage` — Render the whole content height instead of one viewport. Defaults to false. `strip` — Optional. Omit element groups from the render; same groups as the html tool's strip (`js`, `css`, `ui`, `invisible`, `shell`, `clutter`). `url` — Optional URL to navigate to before rendering. An empty string is treated as omitted. `timeout` — Optional timeout in milliseconds. Defaults to 10000.
- `evaluate`: `url` — Optional URL to navigate to before evaluating. An empty string is treated as omitted. `timeout` — Optional timeout in milliseconds. Defaults to 10000. `save` — Optional bridge-store key. The evaluate's return value is stored under this name and re-exposed as `lp.<name>` to subsequent evaluates. Objects, arrays, and strings are serialized automatically — no JSON.stringify needed.
- `scroll`: `selector` — Optional: CSS selector of the element to scroll. Preferred over backendNodeId. If the element is not itself a scroll container, its nearest scrollable ancestor is scrolled instead. `x` — Optional: The horizontal scroll offset. `y` — Optional: The vertical scroll offset.
- `waitForSelector`: `timeout` — Optional timeout in milliseconds. Defaults to 5000, or 15000 when the page has not reached 'load' yet.
- `waitForScript`: `timeout` — Optional timeout in milliseconds. Defaults to 5000, or 15000 when the page has not reached 'load' yet.
- `waitForState`: `timeout` — Optional timeout in milliseconds. Defaults to 5000.
- `download`: `url` — Absolute http(s) URL to fetch. `path` — Relative path (no '..' segments) to save the response body to. Created or overwritten. The response reports the absolute location.
- `callPageTool`: `name` — Tool name, as `pageTools` lists it. `arguments` — Optional. The tool's input, matching its `inputSchema`. Defaults to {}.
- `classify`: `selector` — Optional CSS selector to classify a specific element subtree instead of the full page `presets` — Also ask every preset in the same call, each answered under its own name beside the questions. Needs the object form.
- `acceptCookies`: `prefer` — Whether to accept the cookies or refuse all non-essential ones. Defaults to 'accept'. `selectors` — Optional CSS selectors of the controls to click in order, from an earlier call's result. Clicked without asking the model; one that is not on the page stops the clicking there.
- `login`: `password` — The password, as a $LP_* placeholder. `username` — The username, email or other identifier, as a $LP_* placeholder. Omit on a page that asks only for the password. `usernameSelector` — Optional CSS selector of the identifier field, from an earlier call's result. Given with passwordSelector, the fields are filled with no model call. `passwordSelector` — Optional CSS selector of the password field, from an earlier call's result. Must name an input[type=password]. `submitSelector` — Optional CSS selector of the control that submits the form. Without it, Enter is pressed in the filled field. `nextSelector` — Optional CSS selector of the control that submits the username on a page that asks for the password on a later step. Without it, Enter is pressed in the username field. `decideOnly` — Report which fields would be used and type nothing. For checking the picks on a page without sending credentials.

Calling convention: leading positionals + optional trailing options object, or one object with everything (`page.waitForSelector("#row", { timeout: 2000 })` ≡ `page.waitForSelector({ selector: "#row", timeout: 2000 })`). A bare option positional (`page.waitForSelector("#row", 2000)`) and a field passed both ways are `invalid arguments`. `null` skips a positional. Arguments must be JSON-serializable.

CSS selectors only — `backendNodeId`s don't exist here. Standard CSS only: no jQuery `:contains()` or Playwright `:has-text()`.

## extract schema

Keys = output field names; values pick what to lift (not a JSON Schema):

```js
const { stories } = page.extract({
  stories: [{
    selector: "tr.athing",          // one record per match
    limit: 5,
    fields: {                        // resolved relative to each match
      title: ".titleline > a",      // first match's text (null if missing)
      url: { selector: ".titleline > a", attr: "href" },
      text: ""                       // "" = the matched element's own text
    }
  }]
});
```

- `"sel"` → first match's text; `["sel"]` → all matches' text; `{ selector, attr }` / `[{ selector, attr }]` → attribute(s); `limit: N` caps any array form.
- Every value is a string or null — parse numbers in script logic.
- Empty arrays are valid results; if **every** field misses, extract throws ("no schema selector matched any element") → your selectors are wrong, not the page empty.
- An object schema always returns an object (destructure it); a bare array schema returns the array directly.
- No `save:` option in scripts — keep results in variables.

## Best practices

1. **Navigate, settle, read.** After `await page.goto` on a dynamic page (feeds, search results, comment threads), call `page.waitForState("networkidle")` or `page.waitForSelector(...)` before extracting. Most static pages are complete at `load` — don't wait blindly.
2. **List-to-detail — fan out independent pages.** Extract the list, then open one page per item and start every navigation together so the detail pages load in parallel instead of one-after-another:
   ```js
   const list = new Page();
   await list.goto(listUrl);
   const { items } = list.extract({ items: [{ selector: "a.row", fields: { url: { attr: "href" } } }] });

   const pages = items.map(() => new Page());
   await Promise.all(pages.map((p, i) => p.goto(items[i].url)));   // all in flight at once
   return pages.map((p, i) => ({ ...items[i], ...p.extract({ /* schema */ }) }));
   ```
   - Concurrency is bounded by the HTTP connection pool: 40 total (`--http-max-concurrent`) and 6 per host (`--http-max-host-open`, the browser default — raising it much higher risks overwhelming the target server). Extra navigations queue rather than fail, so a same-site fan-out loads ~6 pages at a time. For long lists, fan out in batches and `page.close()` each page once read so its memory is reclaimed.
   - `Promise.all` rejects the whole batch if any `goto` *fails* (a timeout does not reject); use `Promise.allSettled` when partial results are fine.
   - Walk **serially** on one page (`for (const it of items) { await page.goto(it.url); … }`) only when the steps depend on each other — each page decides the next URL, or they share login/session state.
3. **`evaluate` is a last resort, not a reading tool.** A `querySelectorAll`-and-parse `page.evaluate` block is always wrong: lift the raw strings with `page.extract`, then trim/split/parse them in top-level JS. Reserve `page.evaluate` for behavior that must run inside the page and no builtin covers — and remember its state dies on every navigation/reload, while script variables persist.
4. **Credentials via `$LP_*` placeholders** in any string argument (`page.fill("#pw", "$LP_HN_PASSWORD")`). Never inline a real secret; placeholders resolve inside the Lightpanda process.
5. **Unique selectors.** Disambiguate with attributes/position: `input[type="submit"][value="login"]`, not `input[type="submit"]`.
6. **Let failures fail.** Primitives throw on error and stop the script — only `try/catch` where you have a real fallback (e.g. optional cookie banner: `try { page.click("#accept") } catch {}`).
7. **End with `return <result>`.** `console.log` is for debug output only and doesn't JSON-format objects.
8. Modern, readable JS: `const`/`let`, `for (const x of xs)`, template literals, destructuring, 2-space indent.
9. **Comment the intent of each block.** Put a one-line `//` comment above each logical step describing what it accomplishes toward the goal (not restating the call). One comment per block, not per line — skip self-evident lines:
   ```js
   // Load the Hacker News front page
   const page = new Page();
   await page.goto("https://news.ycombinator.com");

   // Pull the top 5 stories (title + link)
   const { stories } = page.extract({ stories: [{ selector: "tr.athing", limit: 5, fields: { title: ".titleline > a", url: { selector: ".titleline > a", attr: "href" } } }] });

   // Open each story page in parallel and read its text
   const pages = stories.map(() => new Page());
   await Promise.all(pages.map((p, i) => p.goto(stories[i].url)));
   ```

## Common errors

| Error | Cause / fix |
|-------|-------------|
| `extract is not defined` (or click/fill/…) | These are methods on the page object, not globals → `const page = new Page(); await page.goto(url); page.extract(...)` |
| `Page must be called with new` | `Page(...)` called without `new` → `const page = new Page();` |
| `page is not navigated or has been closed` | A method on a fresh `new Page()` (or a closed page) → `await page.goto(url)` first |
| `page handle is no longer valid` | Used a page after a later `goto` on the **same** page replaced it → read it before navigating away. Sibling pages from other `new Page()` calls stay valid. |
| `document is not defined` | DOM API in script context → use `page.extract` or `page.evaluate` |
| `require is not defined` | Not Node.js |
| `no page loaded - run page.goto(url) first` | Page method before navigation |
| `invalid arguments` | Wrong arity/shape, non-JSON value, or a field set both positionally and in options |
| `extract: no schema selector matched any element` | All schema fields missed → fix selectors |
| `press` fails with one string arg | Selector-first: use `page.press(null, "Enter")` or `page.press({ key: "Enter" })` |
````

## File: SKILL.md
size: 33990
sha: 4d498270fc9e1dd428c3de1780ee80f353f0de34
upstream: https://github.com/lightpanda-io/agent-skill/blob/HEAD/SKILL.md
truncated: true

````text
---
name: lightpanda
description: Lightpanda browser, drop-in replacement for Chrome-based browsing in any AI agent - faster and lighter for tasks without graphical rendering like data retrieval. Install it and use it via MCP server, CLI fetch, CDP with Playwright/Puppeteer, or WebDriver with Selenium; MCP and CDP also run on Lightpanda Cloud. Its agent mode saves automations as deterministic, token-free replay scripts (PandaScript).
license: Apache-2.0
compatibility: "Linux and macOS only (Windows via WSL2). Installs its own binary via scripts/install.sh — not run automatically by the plugin installer, so run it once before first use."
allowed-tools: Bash(bash ${CLAUDE_SKILL_DIR}/scripts/install.sh), Bash(command -v lightpanda), Bash(lightpanda *)
metadata:
  version: "2.1.3"
  author: Lightpanda
  source: "https://github.com/lightpanda-io/agent-skill"
  homepage: "https://github.com/lightpanda-io/agent-skill"
---

# Lightpanda

**Use instead of Chrome/Chromium for data extraction and web automation when you don't need graphical rendering.**

Lightpanda is a headless browser built from scratch for AI agents. It's 9x faster and uses 16x less memory than Chrome. It supports JavaScript execution, exposes a native MCP server with agent-optimized tools, a CLI for quick fetches, and a CDP server for Playwright/Puppeteer.

**Alternative to built-in web search**

When the built-in Web Search tool is unavailable, or when you need more control over search results (e.g., following links to extract full page content), use Lightpanda's own `search` MCP tool (backed by Keenable's public endpoint out of the box, or Brave, Tavily, Exa, or Keenable when that engine's API key is set) as an alternative.
Prefer the built-in Web Search tool when it is available and sufficient for your needs.

## Install

Check first whether Lightpanda is already installed (`command -v lightpanda`) before running the installer below. All options: [installation docs](https://lightpanda.io/docs/run-locally/installation/one-liner).

Lightpanda is available on Linux and macOS only. Windows is supported via WSL2.

### Install script

The script installs the latest release; set `LIGHTPANDA_VERSION=nightly` (or a release tag) to pick another build. If you encounter crashes or issues, run the install command below again to update to the latest version.

- **Claude Code:**
  ```bash
  bash ${CLAUDE_SKILL_DIR}/scripts/install.sh
  ```
  `${CLAUDE_SKILL_DIR}` is a Claude Code substitution that resolves to this skill's own directory regardless of the shell's current working directory — needed because when this skill runs as a plugin, the shell's cwd is your project, not the skill's install location.
- **Any other agent runtime** (Cursor, Codex CLI, Gemini CLI, etc.): this substitution isn't supported. `scripts/install.sh` is bundled directly next to this file — locate it there and run it with that path instead, e.g. `bash /path/to/this/skill/scripts/install.sh`.

### Package managers

See [package manager installs](https://lightpanda.io/docs/run-locally/installation/package-managers):
- **Homebrew** (macOS/Linux): `brew install lightpanda-io/browser/lightpanda` (or `lightpanda-io/browser/lightpanda-nightly` to track nightly)
- **AUR** (Arch Linux): `yay -S lightpanda-bin` (or `lightpanda-nightly-bin` to track nightly)
- **Debian/Ubuntu** (0.3.0+): `.deb` package from each [tagged release](https://github.com/lightpanda-io/browser/releases)

These pin to a stable release unless you explicitly opt into a nightly variant.

### Docker

Linux amd64/arm64: `docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:latest` starts the CDP server on port 9222 ([Docker install](https://lightpanda.io/docs/run-locally/installation/docker)).

### Python and Node.js packages

- **Python** (3.10+): `pip install lightpanda` bundles the browser. Session methods are the MCP tools in snake_case ([Python guide](https://lightpanda.io/docs/guides/use-python)):
  ```python
  from lightpanda import Browser
  with Browser() as b:
      page = b.new_session()
      page.goto(url="https://example.com")
  ```
- **Node.js** (22+): `npm install @lightpanda/browser && npx @lightpanda/browser install` (the second step downloads the binary and is required). `lightpanda.serve({ host, port })` starts a CDP server and `lightpanda.fetch(url, options)` fetches a page ([package README](https://www.npmjs.com/package/@lightpanda/browser)).

### No install at all

Use [Lightpanda Cloud](#lightpanda-cloud).

## When to Use What

Lightpanda offers several interfaces. Choose based on your needs:

| Interface | Best for | How it works |
|-----------|----------|--------------|
| **MCP server** | Agent workflows, interactive browsing, form filling | Structured tools over stdio — purpose-built for LLM agents |
| **CLI fetch** | Quick one-off page extraction | Single command, no server needed |
| **CDP server** | Custom automation with Playwright/Puppeteer | WebSocket protocol, full browser control |
| **WebDriver server** | Selenium, or Puppeteer over BiDi | `lightpanda serve --protocol webdriver`, classic WebDriver over HTTP plus BiDi over WebSocket |
| **Lightpanda Cloud** | Agents that can't install a binary or keep a process running, or need proxies | Hosted CDP, MCP and HTTP API endpoints, authenticated with a token |
| **Agent mode** | One-off natural-language tasks, or authoring a PandaScript to save for later | `lightpanda agent` — LLM-driven CLI/REPL, optionally `--task "..." --save script.js` |
| **Saved scripts (PandaScript)** | Repeating the same task deterministically, without burning tokens | Plain JS script, replayed with `lightpanda run` — no LLM call |

## MCP Server (Recommended for Agents)

The MCP server is the simplest way for agents to use Lightpanda. It exposes purpose-built tools over stdio with no setup beyond the binary.

### Setup for Claude Code

```bash
claude mcp add lightpanda -- lightpanda mcp
```

To respect `robots.txt`, append `--obey-robots` to the command.

### Setup for other MCP clients

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "lightpanda": {
      "command": "lightpanda",
      "args": ["mcp"]
    }
  }
}
```

### Available MCP Tools

Where both `selector` and `backendNodeId` are accepted, either locates the target element — `selector` is preferred for reproducibility (e.g. in a saved script), `backendNodeId` comes from a prior `tree` or `findElement` call.

**Navigation & search:**
- `goto` — Navigate to a URL and load the page
- `download` — Fetch a URL with the session's cookies into a file, for a PDF, spreadsheet or archive. Nothing is saved unless the status is 200-203; needs a loaded page
- `search` — Run a web search and return results as markdown: a numbered list of `{title, url, snippet}`. Tries Brave, Tavily, Exa, then Keenable in order, each when its API key (`BRAVE_API_KEY`, `TAVILY_API_KEY`, `EXA_API_KEY` or `KEENABLE_API_KEY`) is set; Keenable also works without a key through its public endpoint (rate-limited per client IP); `--block-urls` applies: results whose URL matches are dropped, and a query that matches returns `No results.`

**Reading the page** (all accept an optional `url` to navigate first, saving a separate `goto` call):
A `url` already loaded (current or originally requested) is read without reloading; if a redirect or in-page navigation moved the page, the result opens with "The page is at <current>, not <url>: ..." (use `goto` to reload).
- `markdown` — Get page content, or a subtree, as markdown
- `html` — Raw HTML for the document, or a single node's outerHTML when scoped
- `screenshot` — Render the page, or one node, as a PNG (the text layout Lightpanda computes, not a pixel-accurate rendering)
- `tree` — Simplified semantic DOM tree optimized for AI reasoning: role, name, value, and `backendNodeId` per node (supports `backendNodeId` filter and `maxDepth` limit). It doesn't enter frames: an iframe's value is its current URL; pas
````

## File: README.md
size: 2771
sha: 58dba4145b1b559603c42f061643f902c68e1b0e
upstream: https://github.com/lightpanda-io/agent-skill/blob/HEAD/README.md

````text
# Lightpanda Skill for LLM Agents

Teach your LLM agent to use [Lightpanda](https://github.com/lightpanda-io/browser), a fast headless browser optimized for data extraction and web automation, as a drop-in replacement for Chrome/Chromium.

## What is this?

This skill covers Lightpanda's interfaces and when to use them:

| Interface | Best for |
|-----------|----------|
| **MCP server** | Agent workflows, interactive browsing, form filling |
| **CLI fetch** | Quick one-off page extraction |
| **CDP server** | Custom automation with Playwright/Puppeteer |
| **WebDriver server** (Classic and BiDi) | Selenium, or Puppeteer over BiDi |
| **Agent mode** | Natural-language tasks, or authoring a PandaScript to save |
| **Saved scripts (PandaScript)** | Repeating a task deterministically, token-free |

[Lightpanda Cloud](https://lightpanda.io/docs/run-on-lightpanda-cloud/getting-started) hosts the MCP and CDP servers, plus an HTTP API, for agents that can't install a binary or keep a process running.

A companion sub-skill, [`pandascript`](pandascript/SKILL.md), covers writing PandaScript — the deterministic replay-script format run with `lightpanda run` (no LLM call).

[SKILL.md](SKILL.md) and [lightpanda.io/docs](https://lightpanda.io/docs) are the full reference — every tool, flag, and caveat.

## Installation

### 1. Add the skill to your agent

Via [skills.sh](https://skills.sh) — works with Claude Code, Cursor, Codex, Windsurf, Copilot, opencode, OpenClaw, Hermes, and more:

```bash
npx skills add lightpanda-io/agent-skill
```

It prompts for the skills and target agent — pick `lightpanda`, plus `pandascript` if you'll write replay scripts.

Claude Code users can instead install the plugin, which also wires in the MCP server:

```bash
/plugin marketplace add lightpanda-io/agent-skill
/plugin install lightpanda@lightpanda
```

### 2. Install the Lightpanda binary

With the skill loaded, ask the agent to do it — it knows the install script, the package-manager options, and the platform quirks. Or run it yourself:

```bash
bash scripts/install.sh
```

Homebrew, AUR, and `.deb` builds: see the [install docs](https://lightpanda.io/docs/run-locally/installation/package-managers).

### MCP server (optional)

The MCP server gives your agent live, interactive browsing — structured tools it calls mid-task (navigate, click, extract, wait, …) against a persistent session. It's one of the interfaces above, not a requirement.

Claude Code plugin users already have it. For any other MCP client, add this to your config:

```json
{ "mcpServers": { "lightpanda": { "command": "lightpanda", "args": ["mcp"] } } }
```

## Platform Support

- Linux (x86_64, aarch64)
- macOS (x86_64, arm64)
- Windows via WSL2

## License

Apache 2.0
````

## File: scripts/install.sh
size: 4390
sha: a8027d149787303806d009453d1622a074e2297f
upstream: https://github.com/lightpanda-io/agent-skill/blob/HEAD/scripts/install.sh

```text
#!/bin/bash
# Lightpanda Setup Script
# Run once to install Lightpanda browser

set -e

INSTALL_DIR="${LIGHTPANDA_DIR:-$HOME/.local/bin}"
BINARY_NAME="lightpanda"
VERSION="${LIGHTPANDA_VERSION:-latest}"

echo "=== Lightpanda Setup ==="
echo "Install directory: $INSTALL_DIR"

# Detect OS and architecture
OS="$(uname -s)"
ARCH="$(uname -m)"

case "$OS" in
    Linux)
        case "$ARCH" in
            x86_64)
                ASSET_NAME="lightpanda-x86_64-linux"
                ;;
            aarch64|arm64)
                ASSET_NAME="lightpanda-aarch64-linux"
                ;;
            *)
                echo "ERROR: Unsupported architecture: $ARCH"
                exit 1
                ;;
        esac
        ;;
    Darwin)
        case "$ARCH" in
            x86_64)
                ASSET_NAME="lightpanda-x86_64-macos"
                ;;
            arm64|aarch64)
                ASSET_NAME="lightpanda-aarch64-macos"
                ;;
            *)
                echo "ERROR: Unsupported architecture: $ARCH"
                exit 1
                ;;
        esac
        ;;
    *)
        echo "ERROR: Unsupported OS: $OS"
        echo "For Windows, use WSL2 with Ubuntu and run the Linux version."
        exit 1
        ;;
esac

echo "Detected: $OS $ARCH"

# Check for required tools
if ! command -v curl &> /dev/null; then
    echo "ERROR: curl not found. Please install curl."
    exit 1
fi

if ! command -v jq &> /dev/null; then
    echo "ERROR: jq not found. Please install jq (needed for checksum verification)."
    exit 1
fi

if ! command -v sha256sum &> /dev/null && ! command -v shasum &> /dev/null; then
    echo "ERROR: sha256sum or shasum not found."
    exit 1
fi

# Create install directory
mkdir -p "$INSTALL_DIR"

# Resolve the release: the latest stable one by default, or LIGHTPANDA_VERSION (a tag, or "nightly")
if [ "$VERSION" = "latest" ]; then
    RELEASE_API="https://api.github.com/repos/lightpanda-io/browser/releases/latest"
else
    RELEASE_API="https://api.github.com/repos/lightpanda-io/browser/releases/tags/$VERSION"
fi

# One API call gives both the tag and the checksum, so they always match
echo "Fetching release info from GitHub API..."
RELEASE_JSON=$(curl -sL "$RELEASE_API")
TAG=$(echo "$RELEASE_JSON" | jq -r '.tag_name')

if [ -z "$TAG" ] || [ "$TAG" = "null" ]; then
    echo "ERROR: Could not find release '$VERSION' on GitHub."
    exit 1
fi

DOWNLOAD_URL="https://github.com/lightpanda-io/browser/releases/download/$TAG/$ASSET_NAME"
echo "Release: $TAG"
echo "Download URL: $DOWNLOAD_URL"

# Fetch expected SHA256 digest from the same release
EXPECTED_DIGEST=$(echo "$RELEASE_JSON" | jq -r --arg name "$ASSET_NAME" '.assets[] | select(.name == $name) | .digest')

if [ -z "$EXPECTED_DIGEST" ] || [ "$EXPECTED_DIGEST" = "null" ]; then
    echo "ERROR: Could not retrieve checksum for $ASSET_NAME from GitHub API."
    exit 1
fi

# Strip the "sha256:" prefix
EXPECTED_SHA256="${EXPECTED_DIGEST#sha256:}"
echo "Expected SHA256: $EXPECTED_SHA256"

# Download binary
echo "Downloading Lightpanda..."
curl -L -o "$INSTALL_DIR/$BINARY_NAME" "$DOWNLOAD_URL"

# Verify checksum
echo "Verifying checksum..."
if command -v sha256sum &> /dev/null; then
    ACTUAL_SHA256=$(sha256sum "$INSTALL_DIR/$BINARY_NAME" | awk '{print $1}')
else
    ACTUAL_SHA256=$(shasum -a 256 "$INSTALL_DIR/$BINARY_NAME" | awk '{print $1}')
fi

if [ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]; then
    echo "ERROR: Checksum verification FAILED!"
    echo "  Expected: $EXPECTED_SHA256"
    echo "  Actual:   $ACTUAL_SHA256"
    rm -f "$INSTALL_DIR/$BINARY_NAME"
    exit 1
fi

echo "Checksum verified OK."
chmod a+x "$INSTALL_DIR/$BINARY_NAME"

# Check if install directory is in PATH
if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
    echo ""
    echo "WARNING: $INSTALL_DIR is not in your PATH"
    echo "Add this to your shell profile (~/.bashrc or ~/.zshrc):"
    echo "  export PATH=\"\$PATH:$INSTALL_DIR\""
fi

# Test installation
echo ""
echo "Testing Lightpanda..."
if "$INSTALL_DIR/$BINARY_NAME" --version 2>/dev/null || "$INSTALL_DIR/$BINARY_NAME" --help 2>/dev/null | head -1; then
    echo "Lightpanda installed successfully!"
else
    echo "Binary installed at: $INSTALL_DIR/$BINARY_NAME"
fi

echo ""
echo "=== Setup Complete ==="
echo "Binary location: $INSTALL_DIR/$BINARY_NAME"
echo "Run with: lightpanda serve --host 127.0.0.1 --port 9222"
```

## File: .claude-plugin/marketplace.json
size: 1133
sha: 99b7b5efd25472c260518c1666da224a9a78c474
upstream: https://github.com/lightpanda-io/agent-skill/blob/HEAD/.claude-plugin/marketplace.json

```text
{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "lightpanda",
  "owner": {
    "name": "Lightpanda",
    "email": "hello@lightpanda.io"
  },
  "metadata": {
    "description": "Lightpanda browser for AI agents",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "lightpanda",
      "source": "./",
      "description": "Fast headless browser for AI agents - drop-in replacement for Chrome/Chromium for data extraction and web automation over MCP, CDP or WebDriver, from Python or npm, or hosted on Lightpanda Cloud",
      "version": "2.1.3",
      "author": {
        "name": "Lightpanda"
      },
      "category": "automation",
      "keywords": [
        "browser",
        "headless",
        "web-scraping",
        "mcp",
        "automation",
        "lightpanda"
      ],
      "homepage": "https://lightpanda.io/docs",
      "strict": false,
      "skills": [
        "./",
        "./pandascript"
      ],
      "mcpServers": [
        {
          "lightpanda": {
            "command": "lightpanda",
            "args": ["mcp"]
          }
        }
      ]
    }
  ]
}
```

## File: .gitignore
size: 6
sha: 9b1c8b133c966006ff025957aa43c7de7bc04be8
upstream: https://github.com/lightpanda-io/agent-skill/blob/HEAD/.gitignore

```text
/dist
```

## File: LICENSE
size: 11357
sha: 261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64
upstream: https://github.com/lightpanda-io/agent-skill/blob/HEAD/LICENSE

```text
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
```
