Skip to content

https://arxiv.org/abs/2606.28344. The end of web parsing. The beginning of scalable pixel-native search. link: https://pixelrag.ai/

feat: ship pixelbrowse as an opencode plugin (#129)

Tauan BF597205002ccf
diff --git a/README.md b/README.md
index 2cae1e5..0598cb3 100644
--- a/README.md
+++ b/README.md
@@ -93,6 +93,18 @@ claude -p "screenshot https://arxiv.org/abs/2404.12387 and explain the key findi
Or use the slash command in an interactive session: `/screenshot https://example.com`.
No MCP server, no backend: the skill just calls `pixelshot` (Playwright/CDP) on your machine.
+**opencode** users get the same `screenshot` tool via the `@startrail/pixelbrowse` npm package
+— with `pixelshot` on `PATH`, add it to `opencode.json`:
+
+```json
+{
+ "$schema": "https://opencode.ai/config.json",
+ "plugin": ["@startrail/pixelbrowse"]
+}
+```
+
+See [`plugin/opencode/`](plugin/opencode/) for details.
+
## How it works
<p align="center">
diff --git a/plugin/README.md b/plugin/README.md
index 68f315a..70e1e10 100644
--- a/plugin/README.md
+++ b/plugin/README.md
@@ -25,3 +25,8 @@ Or use the slash command in an interactive session: `/screenshot <url>`.
The skill lives in `skills/pixelbrowse/SKILL.md`; the command in `commands/screenshot.md`.
No MCP server or backend — the skill just calls `pixelshot` (Playwright/CDP) on your machine.
+
+## opencode
+
+An equivalent opencode plugin (a `screenshot` tool, shipped as the `@startrail/pixelbrowse`
+npm package) lives in [`opencode/`](opencode/).
diff --git a/plugin/opencode/README.md b/plugin/opencode/README.md
new file mode 100644
index 0000000..cd6faa8
--- /dev/null
+++ b/plugin/opencode/README.md
@@ -0,0 +1,47 @@
+# pixelbrowse — opencode plugin
+
+Give opencode eyes: screenshot any URL or document with `pixelshot` and read it visually.
+Adds a `screenshot` tool that renders a page to image tiles (Playwright/CDP) so the agent
+sees charts, diagrams, tables, and layout the way a person does.
+
+## Install
+
+```bash
+pip install pixelrag # provides the pixelshot command (or: uv tool install pixelrag)
+```
+
+Then add the plugin to your `opencode.json`:
+
+```json
+{
+ "$schema": "https://opencode.ai/config.json",
+ "plugin": ["@startrail/pixelbrowse"]
+}
+```
+
+opencode installs npm plugins automatically at startup. For local development from a
+clone, symlink or copy `index.js` into `~/.config/opencode/plugins/` (global) or
+`.opencode/plugins/` (project) — files there are loaded directly at startup.
+
+## Use
+
+Just ask opencode to look at a page:
+
+```
+opencode run "screenshot https://news.ycombinator.com and summarize the top stories"
+```
+
+The agent calls the `screenshot` tool with a URL (or a local HTML file, PDF, or image),
+gets back the tile image paths, and reads them visually. Optional tool args: `output`
+(tile directory, default `/tmp/pixelbrowse`) and `viewportWidth` (default 875; use 1280
+for desktop layouts).
+
+No MCP server, no backend — the plugin just calls `pixelshot` on your machine.
+
+## Publishing (maintainers)
+
+The package is published manually from this directory:
+
+```bash
+npm publish --access public
+```
diff --git a/plugin/opencode/index.js b/plugin/opencode/index.js
new file mode 100644
index 0000000..56d833b
--- /dev/null
+++ b/plugin/opencode/index.js
@@ -0,0 +1,120 @@
+import { tool } from "@opencode-ai/plugin"
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+
+const DESCRIPTION = `Screenshot a web page or document with pixelshot and read it visually.
+
+Use instead of fetching raw HTML when you need to see what a page looks like,
+read visual content (charts, diagrams, infographics, tables), check layouts, or verify UI.
+
+Runs pixelshot (Playwright/CDP) locally and returns the tile image paths — read them
+with the Read tool, in order. tile_0000.jpg is the top of the page; higher numbers go
+further down. Tiles are rendered at 1568px height for optimal vision-model readability.
+
+If text or details are too small to read, crop the region of interest from a tile and
+re-read at full resolution. Pillow is always available (it's a pixelshot dependency):
+ python3 -c "from PIL import Image; Image.open('<tile>').crop((x1, y1, x2, y2)).save('/tmp/pixelbrowse/crop.png')"
+Crop to roughly 800x800 or smaller for maximum clarity.`
+
+const INSTALL_HINT =
+ "`pixelshot` was not found on PATH. Install it (isolated, on PATH): " +
+ "`uv tool install pixelrag` (or `pipx install pixelrag`, or `pip install pixelrag`), then retry."
+
+// Newest *.tiles directory under `output` (pixelshot writes <output>/<name>.tiles/tile_NNNN.jpg).
+function latestTilesDir(output) {
+ if (!existsSync(output)) return null
+ const dirs = readdirSync(output)
+ .filter((name) => name.endsWith(".tiles"))
+ .map((name) => join(output, name))
+ .filter((path) => statSync(path).isDirectory())
+ if (dirs.length === 0) return null
+ return dirs.reduce((a, b) => (statSync(a).mtimeMs >= statSync(b).mtimeMs ? a : b))
+}
+
+// tiles.json is the manifest pixelshot writes beside the tiles: the ordered tile
+// list, plus `complete`, which is false when the capture could not be trusted to
+// cover the whole page. Returns null if it is missing or unreadable, in which case
+// the caller falls back to scanning the directory.
+function readManifest(tilesDir) {
+ try {
+ return JSON.parse(readFileSync(join(tilesDir, "tiles.json"), "utf8"))
+ } catch {
+ return null
+ }
+}
+
+export const PixelbrowsePlugin = async ({ $ }) => {
+ return {
+ tool: {
+ screenshot: tool({
+ description: DESCRIPTION,
+ args: {
+ target: tool.schema
+ .string()
+ .describe("URL (http/https), or path to a local HTML file, PDF, or image"),
+ output: tool.schema
+ .string()
+ .optional()
+ .describe("Output directory for tiles (default /tmp/pixelbrowse)"),
+ viewportWidth: tool.schema
+ .number()
+ .optional()
+ .describe(
+ "Viewport width in px (default 875, mobile/article width). Use 1280 for desktop layouts."
+ ),
+ },
+ async execute(args) {
+ const output = args.output ?? "/tmp/pixelbrowse"
+
+ try {
+ await $`which pixelshot`.quiet()
+ } catch {
+ return `ERROR: ${INSTALL_HINT}`
+ }
+
+ const cliArgs = [args.target, "--output", output, "--tile-height", "1568"]
+ if (args.target.startsWith("http://") || args.target.startsWith("https://")) {
+ cliArgs.push("--wait-network-idle")
+ }
+ if (args.viewportWidth) cliArgs.push("--viewport-width", String(args.viewportWidth))
+
+ let result
+ try {
+ result = await $`pixelshot ${cliArgs}`.quiet()
+ } catch (err) {
+ return `ERROR: pixelshot failed:\n${err.stderr?.toString() ?? err.message}`
+ }
+
+ const tilesDir = latestTilesDir(output)
+ if (!tilesDir) {
+ return `ERROR: pixelshot ran but produced no tiles in ${output}.\n${result.stdout.toString()}`
+ }
+
+ const manifest = readManifest(tilesDir)
+ const names = manifest?.tiles?.length
+ ? manifest.tiles
+ : readdirSync(tilesDir)
+ .filter((name) => /^tile_\d+\.(jpg|png)$/.test(name))
+ .sort()
+ const tiles = names.map((name) => join(tilesDir, name))
+
+ if (tiles.length === 0) return `ERROR: no tile images found in ${tilesDir}`
+
+ const lines = [
+ `Rendered ${args.target} to ${tiles.length} tile(s). Read them with the Read tool, in this order:`,
+ ...tiles,
+ ]
+ if (manifest?.complete === false) {
+ lines.push(
+ "",
+ "WARNING: the manifest reports complete: false — pixelshot could not confirm " +
+ "it measured the whole page, so these tiles may be only the top of it. " +
+ "Report that alongside what you saw rather than presenting it as the full page."
+ )
+ }
+ return lines.join("\n")
+ },
+ }),
+ },
+ }
+}
diff --git a/plugin/opencode/package.json b/plugin/opencode/package.json
new file mode 100644
index 0000000..ffdca4a
--- /dev/null
+++ b/plugin/opencode/package.json
@@ -0,0 +1,31 @@
+{
+ "name": "@startrail/pixelbrowse",
+ "version": "0.1.0",
+ "description": "Give opencode eyes — screenshot any URL or document with pixelshot and read it visually",
+ "license": "Apache-2.0",
+ "type": "module",
+ "main": "index.js",
+ "publishConfig": {
+ "access": "public"
+ },
+ "files": [
+ "index.js",
+ "README.md"
+ ],
+ "keywords": [
+ "opencode",
+ "opencode-plugin",
+ "pixelrag",
+ "pixelshot",
+ "screenshot"
+ ],
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/StarTrail-org/PixelRAG",
+ "directory": "plugin/opencode"
+ },
+ "homepage": "https://github.com/StarTrail-org/PixelRAG",
+ "dependencies": {
+ "@opencode-ai/plugin": "^1.18.9"
+ }
+}