# Vibium: a verification layer that lets coding agents drive a browser from the CLI

> Vibium is an Apache-2.0 Go binary that gives coding agents browser control through CLI commands, an MCP server, and JS, Python and Java clients. It is early, it ships nightly builds, and its whole value depends on whether your agent can check its own work.

**VibiumDev/vibium** — The verification layer for coding agents

- Repository: https://github.com/VibiumDev/vibium
- Website: https://vibium.com
- Stars: 2,935 · Forks: 187
- Language: Go
- License: Apache-2.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/vibiumdev-vibium

## The problem Vibium targets: agents that cannot check their own output

A coding agent that edits a login form has no way to confirm the form still submits. It can read the diff, run unit tests, and guess. Vibium's answer is to hand the agent a browser it can drive with short shell commands, so the verification step is something the agent performs rather than something a human performs afterwards. The README frames this directly: Vibium gives AI agents the tools they need to check their work, and installs as a skill so the agent learns the browser automation toolkit.

The audience is narrow and specific. This is for teams already running an agent such as Claude Code, Codex or Gemini, and for engineers who want the same browser control from a script in JavaScript, Python or Java. It is not aimed at QA organisations looking for a test runner. There is no assertion library, no test report format and no parallel execution story in the README. The pitch is the agent loop, not the test suite.

## How the CLI, MCP server and language clients sit on one binary

The architecture diagram in the README shows an LLM or agent at the top with two paths down: CLI over Bash, and MCP over stdio. Both land in the same Vibium binary, which contains the CLI commands and the MCP server. The binary then talks to the browser. The README states that this is built on WebDriver BiDi rather than a proprietary protocol, which is the design decision that matters most for anyone evaluating lock-in.

The CLI workflow is built around element references. You navigate with vibium go, then run vibium map to assign references such as @e1 and @e2 to interactive elements, then act on those references. The README calls this the core workflow. There is also a diff map command, which reports what changed. That is the piece that makes an agent loop practical: the agent can compare the page before and after an action instead of re-reading everything.

Element lookup is semantic rather than CSS-based. The README lists find text, find label, find placeholder and find role. For an agent, this matters because generated selectors are brittle. Asking for the element whose visible text is "Sign In" survives a class rename; a generated CSS path usually does not. The trade-off is that semantic lookup depends on the page having sensible text and labels, which is not always true of generated markup.

## Installing Vibium and running the first go, map, click sequence

The README gives npm as the install path for the agent setup. The first command installs Vibium and the vibium binary and downloads Chrome. The second installs the skill into the project's .agents/skills/vibium directory, using the open agent skills CLI, which npx runs without a global install.

```bash
npm install -g vibium
npx skills add https://github.com/VibiumDev/vibium --skill vibe-check
```

After that, the agent has four commands that form the working loop. Navigate, map the page, act on a reference, then diff to see what changed. The README presents exactly this sequence as the core workflow.

```bash
vibium go https://var.parts
vibium map
vibium click @e1
vibium diff map
```

What you should see is a set of references printed by map, a click that succeeds against one of them, and a diff that shows the page state changed. If map returns nothing useful, the page is probably rendering its interactive elements in a way the semantic finders cannot see, and that is the first thing to investigate.

If you prefer structured tool calls over shell commands, the MCP server is registered with the agent instead. The README gives the Claude Code and Gemini CLI forms.

```bash
claude mcp add vibium -- npx -y vibium mcp
gemini mcp add vibium npx -y vibium mcp
```

For library use, npm install vibium covers JavaScript and TypeScript, and pip install vibium covers Python. Both install the Vibium binary and download Chrome, so there is no separate browser setup step. Java is distributed as com.vibium:vibium:26.8.21 through Maven or Gradle. The JS client offers an async API and a separate sync entry point at vibium/sync; the Python package exposes vibium.async_api.browser for async work and vibium.browser as the sync default.

## Nightly releases and what that means for a dependency

Every release listed for this repository is a nightly build, and the most recent one is dated 2026-08-28. The repository is not archived, and the last push was on 2026-08-28. There is no stable release line visible in the release list, only nightly- prefixed tags. The package.json in the monorepo carries version 26.8.21, and the Java dependency example in the README pins the same 26.8.21, so the published artifacts are versioned even though the release feed shows nightlies.

Read that as a warning about upgrade cost rather than a defect. If you pin to a published version, you inherit whatever behaviour that version had. If you track nightlies, you are testing someone else's in-progress work. The README does not describe a support policy, a deprecation window, or a rollback procedure for the binary. For a tool that an agent calls unattended, the absence of a documented rollback path is the thing I would want clarified before putting it in a pipeline.

## Where Vibium is the wrong tool

Vibium is not a test framework. There is no mention in the README of assertions, test discovery, retries, reporters, or CI integration. If your need is a regression suite that runs on every pull request and produces a JUnit file, Vibium does not address it, and the roadmap does not promise it either. The roadmap lists Cortex, described as a memory and navigation layer, Retina, described as a recording extension, and AI-powered locators. Those are future items, not current capabilities.

The second limitation is platform and browser coverage. The platform table lists Linux x64, macOS x64, macOS arm64 and Windows x64. Chrome is the default browser and Firefox is supported through a documented switch, with Firefox 154+ able to record video of a session. If you need Safari, or a mobile device farm, nothing in the README suggests a path. The architecture is a desktop browser binary, not a device grid.

The third is the semantic locator strategy itself. find text, find label, find placeholder and find role all depend on the page exposing meaningful text, labels or ARIA roles. On a canvas-heavy application, or one where interactive elements are divs with click handlers and no roles, map has little to work with. That is a real boundary, and it is the first thing a trial should probe.

## Vibium compared with Selenium and Playwright

The comparison people search for is Vibium versus Selenium, and the difference is one of audience rather than capability. Selenium is a long-standing browser automation standard with a large ecosystem of language bindings and grid infrastructure. Its unit of work is a test session, and its users are test engineers. Vibium's unit of work is a single verification step inside an agent's reasoning loop, and its users are agents and the engineers supervising them. The README positions Vibium against proprietary protocols rather than against Selenium specifically, noting that it is built on WebDriver BiDi.

Against Playwright the split is similar but sharper. Playwright is a test framework with its own runner, tracing, and a broad browser matrix. Vibium ships a roughly 10MB binary with no runtime dependencies and no browser matrix beyond Chrome by default and Firefox by switch. The README's own summary of the difference is that Vibium is AI-native, installed as a skill so the agent learns the toolkit immediately, and that it works as a CLI skill, an MCP server, or a library. If your agent already speaks MCP, the registration is one command. That is the whole adoption cost, and it is also the whole scope.

## Licence, source builds and the real upgrade cost

Vibium is Apache-2.0. That permits commercial use, modification and redistribution, and it includes a patent grant. It also means that if you fork the binary and ship it, you carry the NOTICE file obligations that Apache-2.0 sets out. None of that is unusual, and none of it is legal advice; check the LICENSE and NOTICE files in the repository for the exact terms.

The upgrade cost is concentrated in one place: the binary. Because npm install vibium and pip install vibium both pull the binary and download Chrome, a version bump changes the automation engine itself, not just a wrapper. Source builds are heavier than the install path suggests. The contributing section states that source builds require Go, Node.js and npm, and Java 21, because the default make target builds the Go binary, the JS client and the Java client. The Makefile confirms this with platform-specific Python package variables such as vibium_darwin_arm64 and vibium_linux_x64, and a Windows branch that requires Git Bash as the shell. If you only consume published artifacts, you never touch any of that. If you need to patch the Go binary, you are maintaining a three-language build.

## Conclusion

Adopt Vibium if you already run a coding agent and want it to verify its own browser-facing work through a small CLI surface, and if you can live with nightly builds and a V1 scope that the roadmap describes as the core loop. Do not adopt it as a replacement for a full test framework with reporters, parallel grids and CI integrations, because the README does not describe those. Before committing, install it and run the go, map and diff map sequence against one page of your own application, then confirm which browser your target platform actually gets, since Chrome is the default and Firefox requires the documented switch.

## FAQ

### How does Vibium work?

A single Go binary exposes CLI commands and an MCP server, and drives a browser over WebDriver BiDi. Agents use vibium go to navigate, vibium map to assign element references like @e1, and vibium click to act on them.

### How do you install Vibium?

The README's agent setup installs the package globally with npm install -g vibium, which also downloads Chrome, then adds the skill with npx skills add https://github.com/VibiumDev/vibium --skill vibe-check. Python users install with pip install vibium.

### How do you use Vibium?

The documented core workflow is four commands: vibium go to a URL, vibium map to list interactive elements as references, vibium click @e1 to act, and vibium diff map to see what changed. The same control is available through the MCP server or the JS, Python and Java clients.

### What is Vibium test automation?

Vibium is described as the verification layer for coding agents; the README does not present it as a test automation framework. It offers browser control through CLI commands, an MCP server, and JS, Python and Java client libraries, without assertions or test reporting.

### Is Vibium open source?

Yes. The repository carries the Apache-2.0 licence, and the README links to the LICENSE file. Source builds are documented in CONTRIBUTING.md and require Go, Node.js/npm and Java 21.

### How does Vibium compare with Selenium?

Selenium is a general browser automation standard aimed at test engineers and test sessions. Vibium is built on WebDriver BiDi and is aimed at agents verifying a single step, distributed as a roughly 10MB binary with CLI, MCP server and JS, Python and Java clients.

## Sources

- [Official documentation](https://vibium.com)
- [Official README](https://github.com/VibiumDev/vibium#readme)
- [Project repository](https://github.com/VibiumDev/vibium)
- [Release notes](https://github.com/VibiumDev/vibium/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vibiumdev-vibium