Vibium: A Browser Verification Layer Built for AI Agents, Not Humans

The Problem: Agents That Cannot See Their Own Work

Coding agents generate code, but they rarely check whether that code renders correctly in a browser. A typo in a selector or a misnamed button passes unit tests and still breaks the UI. Vibium positions itself as the verification layer for exactly this gap. It is for developers who run agents like Claude Code, Codex, or Gemini and want those agents to navigate pages, click elements, fill forms, and take screenshots as part of their workflow. The target user is not a human writing Selenium scripts. It is an agent that needs a simple, repeatable way to inspect its own output. The README frames it as a skill: install the vibium skill, and the agent learns the full browser automation toolkit instantly. That framing matters. It changes the interface from a testing framework to a tool the agent calls through Bash or MCP.

WebDriver BiDi Instead of a Proprietary Protocol

Vibium is built on WebDriver BiDi, a bidirectional protocol that is becoming a standard for browser automation. The README explicitly says it avoids proprietary protocols controlled by large corporations. That is a deliberate architectural choice. WebDriver BiDi gives you a single protocol for both automation and introspection, which fits the agent use case because the agent needs to read the page state as much as it needs to act on it. The alternative, Chrome DevTools Protocol (CDP), is powerful but Chrome-centric and historically tied to a single vendor. By choosing BiDi, Vibium can support Firefox as well as Chrome, and the README notes Firefox 154+ can even record video of a session. This is a real differentiator. It means your agent is not locked into one browser engine, and the protocol is openly specified. The trade-off is that BiDi is younger than CDP, so some advanced automation features may lag.

The Core Workflow: Map, Click, Diff

The central interaction model is a three-step loop. First, `vibium go https://var.parts` navigates to a URL. Then `vibium map` lists all interactive elements and assigns them references like `@e1`, `@e2`. The agent clicks with `vibium click @e1`. Finally, `vibium diff map` shows what changed after the interaction. This is a clever design for agents because it avoids fragile CSS selectors. The agent does not need to guess a selector string. It asks the tool what is on the page, gets a stable reference, and acts on that reference. The `diff map` step gives the agent feedback on whether the click actually changed the UI. That feedback loop is the verification layer. It is not an assertion framework. It is a way for the agent to observe the consequences of its actions. The README also lists semantic find commands: `vibium find text "Sign In"`, `vibium find label "Email"`, `vibium find placeholder "Search"`, and `vibium find role button`. These rely on visible text, form labels, placeholders, and ARIA roles. That approach is more robust than CSS because labels and roles are less likely to change than class names.

Installation and Setup: Zero Config, One Binary

Getting Vibium running is straightforward. The README gives two commands for agent setup. First, `npm install -g vibium` installs the binary and downloads Chrome automatically. Second, `npx skills add https://github.com/VibiumDev/vibium --skill vibe-check` installs the skill to `{project}/.agents/skills/vibium`. The `skills` CLI is an open package manager for agent skills from Vercel Labs. No global install is needed for that step because `npx` runs it directly. There is also an MCP server option. For Claude Code, the command is `claude mcp add vibium -- npx -y vibium mcp`. For Gemini CLI, it is `gemini mcp add vibium npx -y vibium mcp`. The MCP route is for agents that prefer structured tool calls over shell commands. The binary is about 10MB with no runtime dependencies, which is light for a browser automation tool. The platform support matrix lists Linux x64, macOS Intel, macOS Apple Silicon, and Windows x64 as supported. Chrome is the default browser; Firefox is supported with a separate how-to guide.

Client Libraries: Same API in Three Languages

Beyond the CLI, Vibium ships client libraries for JavaScript/TypeScript, Python, and Java. The APIs are nearly identical across languages. In JavaScript, you start a browser, open a page, navigate, take a screenshot, find an element, and click. The Python client offers both async and sync APIs. The sync API is the default; you import from `vibium` for sync and `vibium.async_api` for async. The Java client is minimal: `Vibium.start()`, `bro.page()`, `vibe.go(...)`, `vibe.screenshot()`, `vibe.find("a")`, `link.click()`, `bro.stop()`. This symmetry is a practical advantage. An agent written in one language can switch to another without relearning the interface. The README claims a zero-to-hello-world in five minutes for each language. The installation commands are `npm install vibium` for JS, `pip install vibium` for Python, and for Java a Maven or Gradle dependency with version `26.8.21`. The version number suggests a date-based scheme, which matches the nightly release tags. All client libraries still require the Vibium binary to be present, because they wrap it rather than reimplement the protocol.

Limitations and Wrong Tool Cases

Vibium is not a testing framework. It has no assertion library, no test runner, and no reporting. If you need to write human-readable test cases with expected outcomes, you are better off with a dedicated tool like Playwright or Selenium. Vibium is a tool for agents to observe and act, not for humans to assert. The README does not mention handling iframes, shadow DOM, or multiple tabs. Those are common in complex web apps, and the absence of explicit support is a gap. The command list is short: go, map, click, diff, find, and screenshot. That is enough for basic verification but not for deep interaction with modern single-page apps. Another limitation is the release cadence. The only releases shown are nightly builds with names like `nightly-2026.8.28-dev.20260828200027-d6cd1f3`. There is no stable release listed. That means you are relying on nightly artifacts, which may change behavior without notice. The roadmap mentions planned features like Cortex (memory/navigation layer), Retina (recording extension), and AI-powered locators. Those are not yet available. So if you need those capabilities today, Vibium is not ready.

Alternatives: Playwright and the Agent Skill Approach

The most direct alternative is Playwright. Playwright also supports WebDriver BiDi and provides a full test framework with assertions, fixtures, and parallel execution. The difference in approach is fundamental. Playwright is designed for deterministic, human-authored tests that run in CI. Vibium is designed for an agent to call at runtime, with commands like `map` and `diff` that return state to the agent. Playwright has no concept of a skill or an MCP server. You would have to write a wrapper to expose Playwright to an agent. Vibium ships that wrapper out of the box. Another alternative is to give the agent direct access to a browser via CDP, but that requires managing WebSocket connections and writing your own protocol handling. Vibium abstracts that away. The trade-off is that Playwright has a mature ecosystem, stable releases, and broad documentation, while Vibium is new and nightly-only. For an agent that needs to verify a single page, Vibium is simpler. For a team that needs a reliable test suite, Playwright is the safer choice.

Maintenance, License, and What to Verify First

Vibium is licensed under Apache 2.0, which is permissive and allows commercial use, modification, and distribution without copyleft obligations. That is a low-license-risk choice for a tool you embed in your agent toolchain. The repository is actively pushed, with the last push on 2026-08-28 and nightly releases every few days. That activity signals ongoing development, but it also means the project is pre-1.0. The README states that source builds require Go, Node.js/npm, and Java 21 because the default `make` target builds all three components. If you plan to contribute or build from source, you need all three toolchains. The maintenance cost for a user is low: the binary is self-contained and downloads Chrome automatically. But you must track nightly releases for bug fixes, and there is no stable branch to pin to. Before adopting, verify that your agent runtime can invoke the CLI or MCP without conflicting with existing browser tooling. Also confirm that the supported platforms cover your CI environment. The README lists Linux x64, macOS Intel/ARM, and Windows x64, but not Linux ARM or other architectures. If you run ARM Linux servers, you may be out of luck.

Editorial conclusion

Adopt Vibium if you run coding agents that need to verify their own UI work and you want a lightweight, standards-based driver without proprietary protocols. Skip it if you need a full test framework with assertions and reporting, or if your agents must interact with iframes and shadow DOM beyond basic click-and-fill flows. Before adopting, verify that your target browsers and platforms match the supported matrix, and check the nightly-only release cadence for stability. Also confirm that your agent runtime can call the CLI or MCP without conflicting with existing browser tooling.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes