[STG-2487] feat: static multi-marketplace manifest catalog (browse-only, CLI-only)

[shrey150]

What

Repurposes browserbase/browse-plugin into the dedicated, static (no-codebase) repo that external agent marketplaces SHA-pin. Ships only the browse plugin, in all 5 marketplace formats, CLI-only — a browse CLI skill that shells out via Bash/run_shell_command, no bundled MCP server.

Added — root marketplace manifests (one per format)

File	Format
.claude-plugin/marketplace.json	Claude Code marketplace
.codex-plugin/plugin.json	Codex plugin
.cursor-plugin/marketplace.json	Cursor marketplace (browse-only)
.agents/plugins/marketplace.json	Generic .agents marketplace
.grok-plugin/plugin.json	Grok plugin
gemini-extension.json + GEMINI.md	Gemini CLI extension (context-file skill, no MCP)
plugin.json (repo root)	Open Plugin spec v1.0.0 manifest — lets vendor-neutral installers (e.g. npx plugins add browserbase/browse-plugin, Vercel's cross-client CLI) discover this repo directly instead of relying on its skills/-directory fallback heuristic. No mcp.json added alongside it — optional per spec, and this plugin intentionally ships no MCP servers (see "Why CLI-only" below).

Added — per-plugin manifests under plugins/browse/

.claude-plugin/, .codex-plugin/, .cursor-plugin/, .grok-plugin/ plugin.json each referencing ./skills/ and assets/logo.svg. The canonical browse CLI SKILL.md (copied from stagehand/packages/cli/skills/browse/) lands at skills/browse/SKILL.md (repo root, post-flatten) with its name/description frontmatter intact.

SKILL.md freshness

There's no auto-sync yet (stagehand#2330 is still a draft proposal), so skills/browse/SKILL.md is a manual, point-in-time copy of stagehand/packages/cli/skills/browse/SKILL.md. Refreshed once more (2026-07-09) to pull in container/CI --remote guidance, BROWSE_SESSION precedence, and the named-contexts surface (cloud contexts create --name) that had shipped in browse@0.9.1+ but wasn't in this repo's earlier copy. Re-sync by hand until the auto-sync PR lands.

browse@0.9.5 published the same day (npm + ghcr.io/browserbase/browse) — diffed this repo's skills/browse/SKILL.md against stagehand's origin/main copy after that release and they're byte-identical, so this file matches what npm i -g browse actually installs today, not a bleeding-edge main that's ahead of the published package.

Naming and copy fixes (review feedback)

• Dropped the "Browserbase" prefix from "Browserbase browse CLI" everywhere it appeared — just Browse CLI now, across every manifest format and the root plugin.json.
• Renamed the .agents/plugins/marketplace.json marketplace from browserbase-plugins to browserbase, matching the Claude and Cursor marketplace names.
• Aligned Cursor's plugin displayName to "Browse" (was "Browserbase Browse"), matching Codex's.
• Rewrote the shared long description. Surveyed what Exa, Kernel, Parallel, and AgentMail actually ship in their own server.json/plugin.json (not their marketing pages) — all lead with the capability noun and list concrete verbs rather than opening with an imperative. Old: "Automate web browsers with natural language via the Browse CLI." New: "Browser automation for AI agents: navigate, extract, screenshot, and interact with real web pages via a single CLI."
• Dropped a stripe/link-cli reference from the docs — wasn't pulling any weight for a reader trying to understand this repo's layout.
• Rewrote a few passages in README.md/docs/add-a-plugin.md that read as "how we got here" development narrative (earlier revisions, dated sync status) into present-tense statements of the current layout and constraints.

CI: validate on every PR, and keep GEMINI.md from going stale

scripts/validate-template.mjs previously only ran on tag push (release) — a broken manifest or a stale GEMINI.md had no automated signal on a PR. That's exactly how the next item was found: a reviewer happened to read the diff, not because anything enforced it.

• Added .github/workflows/validate.yml: runs the existing validator on every pull_request and on push to main.
• Added a drift check: GEMINI.md's body is generated verbatim from skills/browse/SKILL.md (confirmed byte-identical — Gemini's extension format has no way to reference an external skill file, so the instructions have to live directly in GEMINI.md). scripts/sync-gemini.mjs regenerates it; node scripts/sync-gemini.mjs --check and the main validator both fail if the two drift, with the fix command in the error message. Both sides of the comparison normalize CRLF, so a Windows-checked-out GEMINI.md doesn't false-positive.
• Bugbot caught GEMINI.md itself lagging SKILL.md on this branch (missing container/CI --remote fallback guidance, BROWSE_SESSION precedence, and named cloud contexts) — fixed by porting the missing text verbatim from SKILL.md, which is also what proved the two files are meant to be byte-identical.
• Bugbot also caught two gaps in the check itself: the comparison normalized CRLF on the SKILL.md side only (fixed, tested with a real CRLF-converted GEMINI.md), and validateGeminiSync silently passed if GEMINI.md was missing entirely even though gemini-extension.json requires it (fixed to error in that case, tested by actually deleting the file).
• docs/add-a-plugin.md's layout tree hadn't been updated for either the root plugin.json or the new scripts/ files added earlier in this same PR, so it was already out of sync with the repo it documents. Fixed.
• A final staleness sweep found the same class of bug in every manifest's version field: all five were stuck at 0.9.1, matching neither the browse CLI's actual published npm version (0.9.5) nor this repo's own release tags (v0.1.0 → v0.2.4). First fix pointed plugin.json's version at the CLI's npm version — wrong call, reverted. Checked the actual mechanics: a prior live audit confirmed Cursor's official marketplace listing is built by release.yml, which only runs on a tag push — merging to main alone never updates what Cursor serves. That same audit had already flagged the old repo's in-manifest version disagreeing with its own git tag as a source of confusion; pointing at the CLI's version would have reintroduced exactly that. Checked xAI's and Anthropic's actual draft PR content directly: neither's marketplace format uses a version field in any load-bearing way (xAI has none at all; 240 of 254 real entries in Anthropic's official directory have none, and the 14 that do are frozen at 1.0.0). So plugin.json's version now tracks this repo's own release line instead, bumped to 0.3.0 (next after v0.2.4). scripts/sync-version.mjs propagates it to the other four manifests, and the validator fails CI if they drift or if a required manifest is missing entirely.
• Automated the tagging itself, mirroring a proven pattern already used in stagehand's own release workflow for browse-cli (including the same branch-protection gotcha it hit there): a new tag-release CI job checks plugin.json's currently-committed version against existing tags on every push to main, and pushes a matching vX.Y.Z tag if one doesn't exist yet — no one runs git tag by hand again. It only ever pushes a tag ref, never a commit to main, so it's safe under branch protection. Bugbot caught a real gap in the first version (diffed against the immediate parent commit only, so a version bump split across multiple commits could land without ever getting tagged) — fixed by checking tag existence against the current state directly instead of any commit diff, which structurally can't have that gap.

README rewrite to match house voice

Compared against browserbase/stagehand's top-level README and the browse CLI's own README: both stay benefit-first (what it does, how to use it) and never defend a design decision or reference a tracked-elsewhere roadmap item. Dropped the "Why CLI-only, not MCP" rationale from README.md (redundant with the plain fact already stated a line above it, and out of place in a README aimed at someone installing the plugin). Trimmed the repo-layout tree and third-party-tool caveat that duplicated docs/add-a-plugin.md verbatim, linking there instead of maintaining the same content in two places. Also removed em dashes from README.md specifically, since it's the human landing point for the repo.

Removed — the de-Playwright, and (later) the de-MCP

Deleted the custom TypeScript MCP server and all app code (plugins/browse/{src,scripts,agent,package.json,package-lock.json,tsconfig.json}, plugins/browse/skills/browser-automation/, plugins/browse/rules/, plugins/functions/). Then, after live-testing the hosted-MCP wiring (see "Why CLI-only" below), removed it too: mcpServers stripped from every plugin.json, .mcp.json (root + per-plugin) and server.json deleted, gemini-extension.json rewritten to a plain CLI-context extension. Net across both changes: +926 / −3932.

Why CLI-only, not MCP

The plugin originally bundled both a CLI-shelling skill and a hosted-MCP reference (.mcp.json → https://mcp.browserbase.com/mcp) side by side, letting the agent pick either at runtime. Live-testing that MCP path (real marketplace installs, real headless invocations — not just schema validators) found it's currently broken for every client, and not fixable within this PR's scope:

• Every manifest shipped a bare URL with zero auth — no Authorization: Bearer, no x-bb-api-key header, no ?browserbaseApiKey= query param.
• The hosted MCP server accepts all three of those, but requires one for actual tool execution (initialize/tools/list are unauthenticated by design; start/navigate/etc. are not). With none supplied, every real tool call was rejected: {"jsonrpc":"2.0","error":{"code":-32000,"message":"Invalid query parameters"}}. Confirmed independently through two different real clients (Claude Code, Gemini CLI) — same error, same root cause both times.
• Full OAuth 2.1 — which would let each user authenticate without a manifest ever holding a secret — isn't deployed: live-checked https://mcp.browserbase.com/.well-known/oauth-protected-resource and oauth-authorization-server, both 404; zero oauth/authorize|token|register routes exist anywhere in browserbase/core's origin/main.
• This repo is a static, git-pinned, public catalog every external marketplace SHA-pins — there's no safe way to embed a real Browserbase API key in it, and no field in most of these manifest formats for a user to supply their own per-install.

Given that, and that this audience already has shell access (Claude Code, Codex, Cursor, Gemini CLI, Grok all run with a sandbox), a bundled MCP server adds no reach for these clients while introducing a broken/confusing fallback path — in testing, the agent would sometimes pick the (broken) MCP tool over the (working) CLI skill when both were present. CLI-only removes that ambiguity and matches what's actually proven to work. The hosted MCP remains the right integration for shell-less surfaces (ChatGPT, claude.ai) — that's a separate initiative, gated on OAuth for those specific directories, tracked outside this PR.

E2E Test Matrix

Manifest validators (all formats, run against this branch)

Command / flow	Observed output	Confidence / sufficiency
node scripts/validate-template.mjs	Validation passed. (exit 0) + 2 benign warnings: no hooks/hooks.json, no mcp.json (expected now — CLI-only)	Sufficient — Cursor marketplace name kebab-case, owner.name set, non-empty plugins[], source-dir/name match, referenced logo/skills paths + SKILL.md frontmatter all exist. Re-ran clean after the 2026-07-09 SKILL.md refresh.
claude plugin validate . / claude plugin validate . --strict	✔ Validation passed (both)	Sufficient — Claude Code marketplace manifest valid, strict clean.
claude plugin validate plugins/browse / ... --strict	✔ Validation passed (both)	Sufficient — per-plugin manifest valid strict.
gemini extensions validate .	Extension . has been successfully validated.	Sufficient — Gemini CLI accepts the CLI-only extension shape.
codex plugin marketplace add <abs> → codex plugin list → remove	add/list/remove all succeeded, browse@browserbase-plugins resolved at plugins/browse	Sufficient — registration path works.
Grok: catalog validator + index generator (run in the xAI plugin-marketplace clone)	Catalog OK, generated browse entry resolves skills: [{browse, ...}], no mcpServers key	Sufficient for the SHA-pin catalog path. grok CLI itself isn't installed locally — not live-invocation-tested.
npx plugins discover . (Vercel's Open Plugin CLI), before and after adding root plugin.json	Both: Found 1 local plugin(s) — browse, 1 skill	Sufficient — confirms the new manifest is additive only; discovery result is identical with or without it, and node scripts/validate-template.mjs still passes with the same 2 pre-existing benign warnings.
Cursor deeplink encode/decode	round-trips correctly	Sufficient for encoding correctness; not click-tested in a running Cursor instance (GUI, not automatable here).
GEMINI.md/SKILL.md drift check: introduced a real content diff, then a CRLF-only diff	Real diff → Validation failed: GEMINI.md is out of sync... (exit 1). CRLF-only diff → Validation passed. and sync-gemini.mjs --check reports in-sync (no rewrite)	Sufficient — proves the check catches genuine drift (this is what Bugbot's finding on this branch demonstrated live) without false-positiving on line-ending differences.
.github/workflows/validate.yml, triggered by this PR's own commits	validate check: COMPLETED SUCCESS on every push after it was added	Sufficient — the new PR-time CI gate is exercised by this very PR, not just described.

Real install-and-invoke (live, this session — not just validators)

Client	What ran	Result
Claude Code	Real claude plugin marketplace add → install → headless claude -p task ("navigate to example.com, report the title") against the actual repo files	✅ Clean pass. claude plugin details reported MCP servers (0). Transcript shows only Skill/Bash tool calls — the model shelled out to browse open ... --local, got back "title": "Example Domain", answered correctly. Zero mcp__* calls anywhere.
Gemini CLI	Real gemini extensions install ~/Developer/browse-plugin → headless gemini --yolo task, same prompt	✅ Clean pass. Extension shows a Context file (GEMINI.md), no MCP servers. Two run_shell_command calls (browse open ... --local, browse stop), correct answer, zero MCP calls.
Codex	Real codex plugin marketplace add → codex plugin add → headless codex exec, same prompt	⚠️ Partial. Registration and install verified clean (browse@browserbase-plugins installed/enabled). Invocation blocked by this machine's local codex login having an expired OpenAI API key (401 invalid_api_key) — an environment issue unrelated to the plugin; the turn never started so no tool call was attempted. Needs a valid local Codex login to complete.

All three live tests ran against the real, post-change repo files (not scratch copies), with full install → invoke → cleanup, and confirmed the working tree was left unmodified by testing.

Not proven / left for review

• Cursor and Grok are validator/encoding-verified only — no live click-test in a running Cursor instance, and no live grok CLI invocation (not installed locally).
• Codex tool-invocation is unproven on this machine specifically due to a local auth issue, not a plugin defect — worth a quick re-run once codex login is refreshed.

🤖 Generated with Claude Code

---

Note

Medium Risk
Large behavioral change for installers (MCP and in-repo server removed; agents must use shell + external browse CLI), but the diff is manifests, skills, and CI with no in-repo runtime code.

Overview
This PR restructures the repo from a nested plugins/browse TypeScript MCP/Playwright package (plus a separate functions plugin) into a static, root-level browse catalog with no build step or bundled servers.

Distribution model: New per-client manifests at the repo root (Claude, Cursor, Codex, Grok, .agents, Open Plugin plugin.json, and Gemini gemini-extension.json + GEMINI.md). Marketplaces now point "source" at "." instead of plugins/browse; the functions marketplace entry is removed. Agents are expected to use skills/browse/SKILL.md (allowed-tools: Bash) and the globally installed browse CLI, not MCP tools.

Removed: The entire plugins/browse app (mcp-server, bb-browser, package.json/lockfile, mcp.json, old skills/rules) and plugins/functions/. Release workflow no longer runs npm ci/build in plugins/browse; it only validates and tarballs static files.

CI and consistency: Adds .github/workflows/validate.yml (validate on every PR and main push) plus a tag-release job that tags v{plugin.json version} when missing, which triggers release. scripts/validate-template.mjs now enforces GEMINI.md ↔ skills/browse/SKILL.md sync and version alignment across manifests via sync-gemini.mjs / sync-version.mjs. Plugin release version is set to 0.3.0 (repo tags, not npm CLI version).

Docs: README.md and docs/add-a-plugin.md describe the single-plugin, CLI-only layout; CODEOWNERS added for @browserbase/gtm.

^{Reviewed by Cursor Bugbot for commit 03b38b7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 40bcef3. Configure here.}