feat(herdr): add persistent workspace browser plugin and CLI

.changeset/tidy-pandas-browse.md

@@ -0,0 +1,5 @@
+---
+'@browserbasehq/herdr': minor
+---
+
+Add a Herdr plugin and scoped CLI that give each workspace a persistent Browserbase context and each agent a separate live browser session.

README.md

@@ -39,6 +39,7 @@ integrations/
 │       ├── trigger/              # Trigger.dev background jobs & automation
 │       └── vercel/               # Vercel integrations
 ├── packages/                     # Published npm packages
+│   └── herdr/                    # Persistent workspace browsers for Herdr
 └── README.md
 ```
 

packages/herdr/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Browserbase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/herdr/README.md

@@ -0,0 +1,104 @@
+# Herdr Browserbase plugin
+
+Give every Herdr workspace its own Browserbase context. Agents in that workspace get separate live sessions and share the context's cookies and local storage.
+
+## Install
+
+You need Node.js 20 or newer and Herdr 0.9 or newer.
+
+```bash
+herdr plugin install browserbase/integrations/packages/herdr
+```
+
+The Herdr actions work immediately after plugin installation. Install the package command when you also want to control the browser directly from agent terminals:
+
+```bash
+npm install --global @browserbasehq/herdr
+```
+
+This installs `herdr-browse` and its private copy of `browse`. You do not need a global `browse` installation.
+
+Install the bundled agent skill so Codex, Claude Code, and other supported agents automatically choose the workspace-aware command for browser tasks:
+
+```bash
+herdr-browse skills install
+```
+
+Start a new agent session after installation so it discovers the skill. The skill tells agents to use `herdr-browse` instead of calling the underlying `browse` command directly and not to supply their own session name.
+
+For local development:
+
+```bash
+herdr plugin link /path/to/integrations/packages/herdr
+npm --prefix /path/to/integrations/packages/herdr install
+npm --prefix /path/to/integrations/packages/herdr run build
+npm link /path/to/integrations/packages/herdr
+```
+
+Cloud browsing reads credentials from the environment inherited by Herdr:
+
+```bash
+export BROWSERBASE_API_KEY="bb_live_..."
+export BROWSERBASE_PROJECT_ID="..."
+herdr
+```
+
+The plugin never writes these values to its state file. It also disables `browse`'s legacy automatic `.env` loading, so a workspace `.env` cannot silently select a different Browserbase account.
+
+Herdr shows the manifest and both install-time build commands before it runs them. The npm install is scoped to this package and does not install the rest of the integrations monorepo.
+
+## Use
+
+Run commands inside a Herdr workspace:
+
+```bash
+herdr-browse open http://localhost:3000
+herdr-browse snapshot
+herdr-browse click @0-3
+herdr-browse screenshot page.png
+herdr-browse status
+herdr-browse stop
+```
+
+Localhost, loopback addresses, and `.localhost`, `.local`, or `.test` hosts use a clean local browser. Other URLs use Browserbase. Override routing when needed:
+
+```bash
+herdr-browse open https://example.com --local
+herdr-browse open http://localhost:3000 --cloud
+```
+
+`herdr-browse` passes commands and arguments to the bundled `browse` CLI. It adds a session name derived from the current Herdr workspace and agent or pane, which prevents agents from controlling one another's live sessions.
+
+## Persistence and concurrency
+
+The first cloud open creates a Browserbase Context for the workspace. Later sessions load it, and stopping a session saves cookies and local storage back to it.
+
+Agents have separate live browser sessions but share the workspace Context. If several sessions update it concurrently, the last released session wins.
+
+Local browser sessions are isolated and do not keep state after they stop.
+
+Resetting deletes the remote Context and its saved login state:
+
+```bash
+herdr-browse reset
+# Non-interactive:
+herdr-browse reset --yes
+```
+
+## Herdr actions
+
+The plugin registers actions to start a blank cloud browser, inspect its status, and stop it. Use `herdr-browse open <url>` when you want automatic local or cloud routing.
+
+## State
+
+The plugin stores context IDs and session metadata in `HERDR_PLUGIN_STATE_DIR/browser-state.json`. It writes the file atomically under a lock. It does not store API keys, cookies, or local storage. Browserbase stores the persistent browser data in the workspace Context.
+
+When `herdr-browse` runs directly from an agent terminal, Herdr does not inject `HERDR_PLUGIN_STATE_DIR`. The command uses Herdr's standard per-plugin state location instead:
+
+- `$XDG_STATE_HOME/herdr/plugins/browserbase.browser` when `XDG_STATE_HOME` is set
+- `$HOME/.local/state/herdr/plugins/browserbase.browser` on macOS and Linux
+- `%LOCALAPPDATA%\\herdr\\plugins\\browserbase.browser` on Windows
+
+## Marketplace publishing
+
+Herdr discovers plugins from public GitHub repositories whose default branch contains a valid `herdr-plugin.toml` and whose repository has the `herdr-plugin` topic. After this package reaches the default branch, add that topic to `browserbase/integrations`. The marketplace refreshes automatically.

packages/herdr/herdr-plugin.toml

@@ -0,0 +1,30 @@
+id = "browserbase.browser"
+name = "Browserbase Browser"
+version = "0.1.0"
+min_herdr_version = "0.9.0"
+description = "A workspace-scoped browser that keeps its cloud login state."
+platforms = ["linux", "macos"]
+
+[[build]]
+command = ["npm", "install", "--ignore-scripts", "--workspaces=false", "--package-lock=false"]
+
+[[build]]
+command = ["npm", "run", "build"]
+
+[[actions]]
+id = "start"
+title = "Start workspace browser"
+contexts = ["workspace"]
+command = ["node", "dist/cli.js", "open", "about:blank", "--cloud"]
+
+[[actions]]
+id = "status"
+title = "Workspace browser status"
+contexts = ["workspace"]
+command = ["node", "dist/cli.js", "status"]
+
+[[actions]]
+id = "stop"
+title = "Stop workspace browser"
+contexts = ["workspace"]
+command = ["node", "dist/cli.js", "stop"]

packages/herdr/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@browserbasehq/herdr",
+  "version": "0.1.0",
+  "description": "Give every Herdr workspace a persistent Browserbase browser.",
+  "type": "module",
+  "bin": {
+    "herdr-browse": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "herdr-plugin.toml",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/browserbase/integrations.git",
+    "directory": "packages/herdr"
+  },
+  "keywords": [
+    "herdr",
+    "browserbase",
+    "browse",
+    "browser-automation",
+    "persistent-context"
+  ],
+  "author": "Browserbase",
+  "license": "MIT",
+  "dependencies": {
+    "browse": "0.9.6"
+  },
+  "devDependencies": {
+    "@types/node": "25.0.9",
+    "typescript": "7.0.2",
+    "vitest": "4.0.6"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

packages/herdr/skills/herdr-browse/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: herdr-browse
+description: Use herdr-browse for browser navigation, website interaction, screenshots, form filling, and web-app testing inside a Herdr workspace. Prefer it over browse or direct browser automation so Herdr can isolate each agent session and preserve workspace login state.
+compatibility: 'Requires herdr-browse inside a Herdr workspace. Cloud browsing requires BROWSERBASE_API_KEY.'
+license: MIT
+allowed-tools: Bash
+---
+
+# Herdr Browse
+
+Use `herdr-browse` as the browser automation CLI inside a Herdr workspace. It delegates browser operations to the Browse CLI while assigning the current workspace and agent's session automatically.
+
+Do not call `browse` directly and do not pass `--session`. Doing either bypasses Herdr's session isolation and workspace context handling.
+
+## Browser routing
+
+Open the target URL first:
+
+```bash
+herdr-browse open <url>
+```
+
+Herdr uses a local browser for localhost, loopback addresses, and `.localhost`, `.local`, or `.test` hosts. Other URLs use Browserbase and the workspace's persistent context. Override this only when the task requires it:
+
+```bash
+herdr-browse open <url> --local
+herdr-browse open <url> --cloud
+```
+
+Cloud browsing requires `BROWSERBASE_API_KEY`. The workspace context preserves cookies and local storage across cloud sessions. Each agent gets a separate live session.
+
+## Interaction workflow
+
+Inspect the page before acting, then take a new snapshot after navigation or a UI update because element refs can change:
+
+```bash
+herdr-browse snapshot
+herdr-browse click @0-5
+herdr-browse fill @0-8 "search query"
+herdr-browse snapshot
+```
+
+Useful delegated Browse commands include:
+
+```bash
+herdr-browse get url
+herdr-browse get title
+herdr-browse get text body
+herdr-browse screenshot --path page.png
+herdr-browse tab list
+herdr-browse wait load
+herdr-browse doctor --json
+```
+
+Run `herdr-browse <topic> --help` before using unfamiliar Browse commands.
+
+## Lifecycle
+
+Check or stop only the current agent's session:
+
+```bash
+herdr-browse status
+herdr-browse stop
+```
+
+`herdr-browse reset` deletes the entire workspace's remote context and saved login state. Run it only when the user asks to remove that state or resetting it is necessary to complete the task. Use `--yes` only when that destructive action is already authorized.
+
+## Browse.sh skills
+
+Site-specific Browse.sh skill discovery remains available through the wrapper:
+
+```bash
+herdr-browse skills find <domain-or-task>
+herdr-browse skills add <domain>/<task>
+```
+
+Use `herdr-browse skills install` to install or refresh this Herdr-specific skill. Do not run `browse skills install`, which installs instructions for the unwrapped `browse` command.