Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions .github/workflows/publish-opencode.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
name: Publish OpenCode Plugin

on:
push:
branches:
- main
paths:
- "opencode/package.json"
workflow_dispatch:
inputs:
force:
description: "Force publish even if version exists (will fail if already published)"
required: false
default: "false"
type: boolean

permissions:
contents: read
id-token: write

jobs:
publish:
runs-on: ubuntu-latest
defaults:
run:
working-directory: opencode

steps:
- uses: actions/checkout@v4

- uses: actions/setup-node@v4
with:
node-version: 22
registry-url: https://registry.npmjs.org
Comment thread
cursor[bot] marked this conversation as resolved.
Resolved

- name: Get package info
id: pkg
run: |
NAME=$(node -pe "require('./package.json').name")
VERSION=$(node -pe "require('./package.json').version")
echo "name=$NAME" >> "$GITHUB_OUTPUT"
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
echo "Package: $NAME@$VERSION"

- name: Check if version already published
id: check
run: |
if npm view "${{ steps.pkg.outputs.name }}@${{ steps.pkg.outputs.version }}" version 2>/dev/null; then
echo "exists=true" >> "$GITHUB_OUTPUT"
echo "Version ${{ steps.pkg.outputs.version }} already exists on npm"
else
echo "exists=false" >> "$GITHUB_OUTPUT"
echo "Version ${{ steps.pkg.outputs.version }} not yet published"
fi

- name: Install dependencies
if: steps.check.outputs.exists == 'false' || inputs.force == 'true'
run: npm ci --ignore-scripts || npm install --ignore-scripts

- name: Type check
if: steps.check.outputs.exists == 'false' || inputs.force == 'true'
run: npm run check

# Uses npm OIDC trusted publishing - no NPM_TOKEN secret required.
# First-time setup: someone with @browserbasehq npm org access must
# configure this package to trust GitHub Actions from this repo/workflow.
# See: https://docs.npmjs.com/generating-provenance-statements
- name: Publish to npm
if: steps.check.outputs.exists == 'false' || inputs.force == 'true'
run: npm publish --access public --provenance

- name: Skip publish (version exists)
if: steps.check.outputs.exists == 'true' && inputs.force != 'true'
run: |
echo "::notice::Skipping publish - ${{ steps.pkg.outputs.name }}@${{ steps.pkg.outputs.version }} already exists on npm"
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# browse plugin marketplace

Install the [`browse`](https://github.com/browserbase/stagehand/tree/main/packages/cli) CLI as a native plugin in Claude Code, Cursor, Codex, Grok, Muse Code, Gemini CLI, and Google Antigravity.
Install the [`browse`](https://github.com/browserbase/stagehand/tree/main/packages/cli) CLI as a native plugin in Claude Code, Cursor, Codex, Grok, Muse Code, Gemini CLI, Google Antigravity, and OpenCode.

This repo has no application code. It's a set of static JSON manifests that let each agent marketplace install and SHA-pin the `browse` plugin, plus the skill that teaches the agent to drive `browse` from the shell.

Expand All @@ -16,6 +16,7 @@ This repo has no application code. It's a set of static JSON manifests that let
| `.muse-plugin/plugin.json` | Muse Code native plugin (uses the `.agents` marketplace above) |
| `gemini-extension.json` | Gemini CLI extension (`GEMINI.md` context file) |
| `.antigravity-plugin/plugin.json` | Google Antigravity marketplace |
| `opencode/` | OpenCode npm plugin (`@browserbasehq/opencode`) |

See [`docs/add-a-plugin.md`](docs/add-a-plugin.md) for the full repo layout and how to update the plugin.

Expand All @@ -27,6 +28,7 @@ See [`docs/add-a-plugin.md`](docs/add-a-plugin.md) for the full repo layout and
- **Muse Code**: install the native plugin from a local checkout or the marketplace. See [Muse Code setup](docs/muse-code.md).
- **Gemini CLI**: install this repo as an extension (`gemini-extension.json` + `GEMINI.md`).
- **Antigravity**: install with `agy plugin install https://github.com/browserbase/browse-plugin`.
- **OpenCode**: `opencode plugin add @browserbasehq/opencode` or add `"@browserbasehq/opencode"` to `plugins` in your `opencode.jsonc`. Then install the CLI: `npm install -g browse`.

Then just ask your agent:

Expand Down
65 changes: 65 additions & 0 deletions docs/add-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,14 @@ If Browserbase ever needs a second distinct plugin, it belongs in its own dedica
├── assets/logo.svg
├── assets/logo-antigravity.svg # Antigravity logo with transparent padding
├── skills/browse/SKILL.md # YAML frontmatter: name + description
├── opencode/ # OpenCode npm plugin package
│ ├── package.json # npm manifest for @browserbasehq/opencode
│ ├── index.ts # entrypoint (exports v1 + v2)
│ ├── v1.ts # OpenCode 1 plugin hooks
│ ├── v2.ts # OpenCode 2 plugin setup
│ ├── skills.ts # bundled skills loader
│ ├── skills/browse/SKILL.md # copy of the shared skill
│ └── README.md # OpenCode-specific install docs
└── scripts/
├── validate-template.mjs # run by CI and locally, see "Validate" below
├── gemini-sync.mjs # shared logic: derive GEMINI.md's expected content from SKILL.md
Expand Down Expand Up @@ -68,3 +76,60 @@ Fix all reported errors before committing. This also runs in CI on every pull re
- A marketplace `source`/`path` pointing at anything other than `"."` — this repo has no nested plugin folder anymore.
- Editing `skills/browse/SKILL.md` without running `node scripts/sync-gemini.mjs` afterward — CI fails if `GEMINI.md` drifts out of sync.
- Bumping `plugin.json`'s `version` without running `node scripts/sync-version.mjs` afterward — CI fails if the other manifests drift out of sync.

## OpenCode plugin

Unlike the other agent marketplaces that use static JSON manifests, OpenCode supports plugins distributed as npm packages (among other methods like local files). The `opencode/` directory is a publishable npm package (`@browserbasehq/opencode`) that:

- Supports both OpenCode 1 (`plugin` config) and OpenCode 2 (`plugins` config) from the same package
- Bundles the browse skill (a copy of `skills/browse/SKILL.md`)
- Injects `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` into shell commands when present

### CI publishing

The `.github/workflows/publish-opencode.yml` workflow publishes the package to npm automatically when `opencode/package.json`'s version changes on push to main. It uses npm OIDC trusted publishing (no `NPM_TOKEN` secret required).

#### First-time setup (one-time, requires @browserbasehq npm org access)

Before CI can publish, someone with access to the `@browserbasehq` npm organization must:

1. **Create the package on npm** (if it doesn't exist):
```bash
cd opencode && npm publish --access public
```
Or just let the first CI run create it (it will fail, but the package name will be reserved).

2. **Configure trusted publishing** on npmjs.com:
- Go to [npmjs.com/package/@browserbasehq/opencode](https://www.npmjs.com/package/@browserbasehq/opencode) → Settings → Publishing access
- Add a new trusted publisher:
- **Repository**: `browserbase/browse-plugin`
- **Workflow**: `publish-opencode.yml`
- **Environment**: (leave blank for default)

After this one-time setup, CI will publish automatically on version bumps.

### Updating the OpenCode plugin

1. Update `opencode/skills/browse/SKILL.md` when the shared skill changes (currently a manual copy)
2. Bump the version in `opencode/package.json`
3. Merge to main — CI publishes automatically once trusted publishing is configured

For manual publishing (before trusted publishing is set up):
```bash
cd opencode && npm publish --access public
```

### Installing for users

```bash
opencode plugin add @browserbasehq/opencode
npm install -g browse
```

Or in `opencode.jsonc`:

```jsonc
{
"plugins": ["@browserbasehq/opencode"]
}
```
108 changes: 108 additions & 0 deletions opencode/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# @browserbasehq/opencode

[OpenCode](https://opencode.ai) plugin for [Browserbase](https://browserbase.com) browser automation. It gives your agent the [browse CLI](https://github.com/browserbase/stagehand/tree/main/packages/cli) for navigating pages, extracting content, taking screenshots, and interacting with real web pages.

## Installation

The plugin supports OpenCode 2 and OpenCode 1 from the same package.

### OpenCode 2

```bash
opencode plugin add @browserbasehq/opencode
```

Or add it to `opencode.jsonc` yourself:

```jsonc
{
"$schema": "https://opencode.ai/config.json",
"plugins": ["@browserbasehq/opencode"]
}
```

### OpenCode 1

Add it to `opencode.json`:

```json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@browserbasehq/opencode"]
}
```

OpenCode installs the package on the next start.

### Install the browse CLI

The plugin bundles the browse skill, but you need the CLI installed globally:

```bash
npm install -g browse
```

Verify the installation:

```bash
which browse && browse --help
```

## Authentication

### Local browsing (no key required)

For local browser sessions, no API key is needed. The browse CLI uses Chrome or Chromium on your machine:

```bash
browse open https://example.com --local
browse snapshot
browse stop
```

### Browserbase cloud

For remote stealth sessions, proxies, and CAPTCHA solving, set your API key:

```bash
export BROWSERBASE_API_KEY=your-api-key
```

Get a key at [browserbase.com/settings](https://browserbase.com/settings).

Optionally set a project ID:

```bash
export BROWSERBASE_PROJECT_ID=your-project-id
```

The plugin passes these environment variables to shell commands automatically, so the browse CLI is authenticated without manual configuration in each session.

## Skills

The plugin bundles the browse CLI skill, which teaches your agent:

- Opening and navigating web pages
- Taking accessibility snapshots (structured page state)
- Taking screenshots
- Clicking, typing, and interacting with elements
- Managing browser sessions and tabs
- Using Browserbase cloud APIs
- Working with contexts, extensions, and functions

Just ask your agent:

- *"Go to Hacker News and get the top 5 stories."*
- *"Fill out the signup form on example.com."*
- *"Take a screenshot of localhost:3000."*

## Links

- [browse CLI documentation](https://github.com/browserbase/stagehand/tree/main/packages/cli)
- [Browserbase documentation](https://docs.browserbase.com)
- [OpenCode plugin docs](https://opencode.ai/v2/docs/plugins)
- [browse-plugin repository](https://github.com/browserbase/browse-plugin)

## License

MIT
5 changes: 5 additions & 0 deletions opencode/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
import { server } from "./v1.ts";
import { v2 } from "./v2.ts";

// One entrypoint for both hosts: OpenCode 1 calls `server()`, OpenCode 2 reads `id` and `setup()`.
export default { ...v2, server };
57 changes: 57 additions & 0 deletions opencode/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
{
"name": "@browserbasehq/opencode",
"version": "0.4.0",
"description": "Browserbase browse plugin for OpenCode: browser automation, navigation, extraction, screenshots, and interaction via the browse CLI",
"type": "module",
"main": "index.ts",
"files": [
"index.ts",
"v1.ts",
"v2.ts",
"skills.ts",
"skills"
],
"keywords": [
"opencode",
"opencode-plugin",
"browserbase",
"browser",
"automation",
"stagehand",
"browse",
"web-scraping",
"screenshot",
"llm",
"ai"
],
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/browserbase/browse-plugin.git",
"directory": "opencode"
},
"homepage": "https://browserbase.com",
"author": {
"name": "Browserbase",
"email": "support@browserbase.com",
"url": "https://browserbase.com"
},
"scripts": {
"check": "tsc --noEmit"
},
"dependencies": {
"gray-matter": "^4.0.3"
},
"devDependencies": {
"@opencode-ai/plugin": "^1.19.5",
"@opencode/plugin": "^2.2.5",
"@types/node": "^22.0.0",
"typescript": "^5.0.0"
},
"exports": {
".": "./index.ts"
},
"publishConfig": {
"access": "public"
}
}
Loading
Loading