oc-browserless

Browserless plugin for OpenCode using puppeteer-core.

Features

• Web Browsing: Navigate and browse web pages with content extraction and security certificate information
• DuckDuckGo Search: Search the web with raw HTML content
• Screenshots: Capture screenshots in PNG, JPEG, and WebP formats
• PDF Generation: Convert HTML or URLs to PDF documents
• Browser Lifecycle Management: Automatic browser connection management

Installation

Prerequisites

Install Bun if you haven't already:

curl -fsSL https://bun.sh/install | bash

After installation, restart your terminal or source your shell profile:

# For bash
source ~/.bashrc

# For zsh
source ~/.zshrc

# For fish
source ~/.config/fish/config.fish

Verify Bun installation:

bun --version

Global Installation

npm install -g oc-browserless

Project Installation

npm install oc-browserless

Configuration

Add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oc-browserless"]
}

Browserless Setup

Local Browserless

Using Docker:

docker run -p 3000:3000 -e "CONCURRENT=10" browserless/chrome:latest

Or install globally:

npm install -g browserless
browserless --port=3000

Then set environment variable:

export BROWSERLESS_URL=ws://localhost:3000

Remote Browserless

Sign up for browserless.io and get your API key:

export BROWSERLESS_URL=wss://your-browserless-instance.com
export BROWSERLESS_API_KEY=your-api-key

Environment Configuration

Copy the example environment file:

cp .env.example .env

Edit .env with your browserless configuration:

BROWSERLESS_URL=ws://localhost:3000
BROWSERLESS_API_KEY=your-api-key-if-using-remote

Development Setup

1. Clone Repository

git clone https://github.com/rh-id/oc-browserless.git
cd oc-browserless

2. Install Dependencies

bun install

This will install:

• Runtime dependencies (puppeteer-core, @opencode-ai/plugin)
• Development dependencies (ESLint, Prettier, TypeScript)

3. Build Project

bun run build

This will:

1. Compile TypeScript files to JavaScript in dist/ directory
2. Generate type declarations
3. Copy compiled files to .opencode/ for local OpenCode testing

Note: The .opencode/ directory is used for local development with OpenCode. When the package is published to npm, only the dist/ directory is included.

4. Test with OpenCode

Run opencode in the project directory:

opencode

The plugin is automatically loaded from .opencode/plugin/ directory.

Project Structure

oc-browserless/
├── .github/workflows/           # CI/CD workflows
│   ├── build.yml               # Build and test
│   ├── lint.yml                # Linting and formatting
│   └── release.yml             # Automated releases
├── .husky/                    # Git hooks
│   └── pre-commit              # Pre-commit lint-staged
├── .opencode/                  # OpenCode plugin files (compiled for local dev)
│   ├── plugin/                 # Compiled plugin
│   │   └── browserless.js     # Plugin entry point (all code)
│   └── package.json           # Dependencies for local dev
├── dist/                       # Compiled output (published to npm)
│   └── plugin/
│       ├── browserless.js      # Compiled plugin
│       ├── browserless.d.ts    # Type declarations
│       ├── browserless.js.map  # Source map
│       └── browserless.d.ts.map # Type source map
├── scripts/                    # Build scripts
│   └── build-copy.js          # Build copy script
├── src/                        # Source code (TypeScript)
│   └── plugin/
│       └── browserless.ts     # Complete plugin (all code, ~613 lines)
├── Configuration Files
│   ├── .gitignore
│   ├── .gitattributes
│   ├── eslint.config.cjs
│   ├── .prettierrc
│   ├── .env.example
│   ├── .release-please-manifest.json
│   ├── opencode.json
│   ├── package.json
│   └── tsconfig.json
└── Documentation
    ├── README.md
    ├── CONTRIBUTING.md
    └── LICENSE

Plugin Development

For contributors working on the plugin locally:

Local Testing Workflow

1. Make your changes to src/plugin/browserless.ts

2. Build the project:

   bun run build

   This compiles TypeScript and copies the output to .opencode/plugin/ directory

3. The .opencode/ directory is used for local development with OpenCode:

   • It contains the compiled plugin code
   • When the package is published to npm, only the dist/ directory is included
   • Running opencode in the project root automatically loads the plugin from .opencode/plugin/

4. Test your changes:

   opencode

   The plugin is automatically loaded from .opencode/plugin/ directory

5. Iterate:

   • Make changes to src/plugin/browserless.ts
   • Run bun run build to update .opencode/plugin/
   • Test with opencode

Project Structure for Development

src/plugin/
  └── browserless.ts     # Source code (edit this)

dist/plugin/              # Compiled output (published to npm)
  ├── browserless.js
  ├── browserless.d.ts
  └── browserless.js.map

.opencode/plugin/         # Local dev copy (for testing with opencode)
  └── browserless.js      # Same compiled code as dist/plugin/browserless.js

Build Process

The bun run build command:

1. Compiles TypeScript files to JavaScript in dist/ directory
2. Generates type declarations (.d.ts)
3. Copies compiled files to .opencode/ for local OpenCode testing

Note: Always run bun run build after making changes to test them locally.

Usage

The plugin provides the following tools for OpenCode:

Browse Web Pages

// Navigate to a URL and get content
{
  "tool": "browse",
  "args": {
    "url": "https://example.com"
  }
}

DuckDuckGo Search

// Search the web
{
  "tool": "search",
  "args": {
    "query": "TypeScript best practices"
  }
}

Returns:

{
  "success": true,
  "query": "TypeScript best practices",
  "html": "<html>...</html>"
}

Take Screenshot

// Capture screenshot
{
  "tool": "screenshot",
  "args": {
    "url": "https://example.com",
    "path": "./screenshot.png",
    "format": "png",
    "fullPage": true
  }
}

Generate PDF

// Generate PDF from URL
{
  "tool": "pdf",
  "args": {
    "url": "https://example.com",
    "path": "./output.pdf",
    "format": "A4",
    "printBackground": true
  }
}

// Generate PDF from HTML
{
  "tool": "pdf",
  "args": {
    "html": "<html><body><h1>Hello World</h1></body></html>",
    "path": "./output.pdf"
  }
}

Browser Lifecycle

All browser operations automatically manage their own connections:

• No manual start/stop required - tools handle this internally
• Each tool execution creates an isolated browser instance
• Browser sessions are NOT persistent across tool calls
• Browserless supports multiple concurrent connections automatically
• Each tool operates in isolation with no shared state
• No connection reuse - each operation creates fresh browser instance

API Reference

browse

Navigate to and browse web pages.

Argument	Type	Required	Default	Description
url	string	Yes	-	URL to navigate to

Returns:

{
  "success": true,
  "url": "https://example.com",
  "title": "Example Domain",
  "content": "<html>...</html>",
  "certificate": {
    "issuer": "CN=DigiCert Inc",
    "protocol": "TLS 1.3",
    "subjectName": "CN=example.com",
    "subjectAlternativeNames": ["example.com", "www.example.com"],
    "validFrom": 1234567890,
    "validTo": 1234567890
  }
}

The certificate field is null for HTTP connections or when security details are unavailable.

search

Search using DuckDuckGo.

Argument	Type	Required	Default	Description
query	string	Yes	-	Search query

screenshot

Capture page screenshots.

Argument	Type	Required	Default	Description
url	string	No	-	URL to screenshot
path	string	No	-	Output file path
format	enum	No	png	Format: png, jpeg, webp
fullPage	boolean	No	false	Full page screenshot
quality	number	No	-	Quality for jpeg/webp (0-100)
viewportWidth	number	No	-	Viewport width
viewportHeight	number	No	-	Viewport height

pdf

Generate PDF from HTML or URL.

Argument	Type	Required	Default	Description
html	string	No*	-	HTML content
url	string	No*	-	URL to convert
path	string	No	-	Output file path
format	enum	No	A4	Paper format
printBackground	boolean	No	true	Print backgrounds
landscape	boolean	No	false	Landscape mode
marginTop	string	No	0cm	Top margin
marginBottom	string	No	0cm	Bottom margin
marginLeft	string	No	0cm	Left margin
marginRight	string	No	0cm	Right margin

*Either html or url is required.

Development

# Install dependencies
bun install

# Build
bun run build

# Test
bun test

# Lint
bun run lint

# Format
bun run format

Development Workflow

Linting:

bun run lint

Auto-fix linting issues:

bun run lint:fix

Check formatting:

bun run format:check

Auto-fix formatting:

bun run format

Type checking:

bunx tsc --noEmit

Testing:

bun test

CI/CD

Build Workflow

• Runs on push and PR
• Installs dependencies
• Builds project
• Uploads artifacts

Lint Workflow

• Runs on push and PR
• Lints code with ESLint
• Checks formatting

Release Workflow

• Runs on main branch
• Uses release-please for automated versioning
• Publishes to npm on release

Versioning

Uses automated versioning with release-please:

• feat: → Minor version bump (1.x.0)
• fix: → Patch version bump (x.x.1)
• BREAKING CHANGE: → Major version bump (2.0.0)

Troubleshooting

Connection Issues

Error: "Failed to connect to browserless"

• Check BROWSERLESS_URL environment variable
• Ensure browserless instance is running
• Verify WebSocket URL is correct (use ws:// or wss://)
• Verify firewall/network settings

Verify browserless is running:

curl http://localhost:3000/health

Check WebSocket URL format:

• Local: ws://localhost:3000
• Remote: wss://your-browserless.com

Timeout Issues

Error: "Operation timed out"

• Increase timeout in browser options
• Check network connectivity
• Verify URL is accessible

Browser Disconnected

Error: "Browser not connected" or connection failures

• Check BROWSERLESS_URL environment variable
• Ensure browserless instance is running
• Each tool creates its own connection - no manual management needed
• Try running the tool again if connection fails

TypeScript Errors

If you see TypeScript errors about missing types:

Before dependencies are installed (expected):

1. Cannot find module 'puppeteer-core' → Run bun install
2. Cannot find module '@opencode-ai/plugin' → Run bun install
3. Cannot find name 'setTimeout' / URL / process / fetch → Will resolve after bun install

These are not actual errors - they're just TypeScript not being able to resolve types until dependencies are installed.

After dependencies are installed:

1. Restart your TypeScript server in your IDE
2. Clear Bun cache:

rm -rf node_modules
bun install

Build Errors

If build fails:

1. Check TypeScript version:

bun --version

2. Update dependencies:

bun update

Clean Scripts

The project includes several clean scripts for easy cleanup:

# Clean build output only
bun run clean

# Clean build output and dependencies
bun run clean:deps

# Clean build output and all dependencies
bun run clean:all

# Full reset: clean everything, reinstall dependencies, and rebuild
bun run reset

Use these when:

• clean - After making changes to TypeScript files
• clean:deps - When dependencies need reinstalling
• clean:all - When you want a fresh start
• reset - When troubleshooting build or cache issues

Troubleshooting Build Issues

If you encounter build errors:

# Option 1: Full reset
bun run reset

# Option 2: Manual clean and rebuild
rm -rf dist
bun run build

Donate / Sponsor

If you find this project useful and would like to support its continued development, consider making a donation or becoming a sponsor:

https://teer.id/rh-id

Your support helps maintain and improve the project. Thank you! ❤️

License

MIT © Ruby Hartono

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub Issues page.