⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
lightpanda
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).
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Lightpanda Skill for LLM Agents
Teach your LLM agent to use Lightpanda, 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 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, covers writing PandaScript — the deterministic replay-script format run with lightpanda run (no LLM call).
SKILL.md and lightpanda.io/docs are the full reference — every tool, flag, and caveat.
Installation
1. Add the skill to your agent
Via skills.sh — works with Claude Code, Cursor, Codex, Windsurf, Copilot, opencode, OpenClaw, Hermes, and more:
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:
/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 scripts/install.sh
Homebrew, AUR, and .deb builds: see the install docs.
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:
{ "mcpServers": { "lightpanda": { "command": "lightpanda", "args": ["mcp"] } } }
Platform Support
- Linux (x86_64, aarch64)
- macOS (x86_64, arm64)
- Windows via WSL2
License
Apache 2.0
// HOW IT'S BUILT
// FILES
7 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
pandascript/SKILL.md15 KB7a0b8e554376upstream ↗
--- 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" })` |SKILL.md33 KB4d498270fc9etruncatedupstream ↗
Showing the inlined prefix. The rest is in the upstream file.
--- 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; pasREADME.md2.7 KB58dba4145b1bupstream ↗
# 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.0scripts/install.sh4.3 KBa8027d149787upstream ↗
#!/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".claude-plugin/marketplace.json1.1 KB99b7b5efd254upstream ↗
{ "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", "name": "lightpanda", "owner": { "name": "Lightpanda", "email": "[email protected]" }, "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"] } } ] } ] }.gitignore6 B9b1c8b133c96upstream ↗
/distLICENSE11 KB261eeb9e9f8bupstream ↗
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.
Plain-text copy, no login: /skill-bundles/lightpanda-io-agent-skill.md