vibatchium

<!-- Absolute URL on purpose: PyPI renders this same README and cannot resolve
     repo-relative paths. Pinned to master so it survives tag churn. -->
<p align="center">
  <img src="https://raw.githubusercontent.com/trueoriginlabs/vibatchium/master/assets/vb-logo.png" alt="vibatchium" width="180">
</p>

# vibatchium

<!-- mcp-name: io.github.trueoriginlabs/vibatchium -->

**Agent-piloted browser automation that clears Cloudflare.**
Patched Playwright + multi-session daemon + credential vault + vision clicking + prompt-injection safety. One MCP server, N parallel Chromes, persistent per-session profiles.
Plus two renderer-free lanes on a Chrome TLS fingerprint: **`vb search`** to find
URLs without a search API, **`vb fetch`** to read them — both with per-request
`--proxy`, because engines and walls both rate-limit per IP.

> **Where this fits.** Both Anthropic and Google now ship an agent that drives
> *your own* signed-in Chrome — Claude in Chrome and Chrome Auto Browse. If that
> is what you want, use them: they are free, first-party, and better integrated.
> They are also **supervised** — visible window, real time, and they hand control
> back to you at a login wall or a CAPTCHA. vibatchium is for the other half:
> **unattended, headless, N-at-a-time**, on a box with no human in front of it,
> against sites that fight automation. That is the whole of the wedge, and it is
> worth being precise about which side of it you are on.
>
> **2026-09-15 sharpened the split.** For new domains and free-plan zones,
> Cloudflare now blocks *Training* and *Agent* crawlers by default on
> ad-monetized pages, leaving *Search* allowed; existing paid zones keep the
> settings they had. That default targets crawlers which **declare themselves** — by user-agent, or
> by a Web Bot Auth signature — and it catches multi-purpose crawlers along with
> the dedicated ones. It does not change what a real Chrome session looks like,
> so the lane this tool works in is untouched by the rule itself. Be precise
> about the limit, though: it is a change to *policy defaults*, not to
> detection. The fingerprint and behavioural scoring under
> [Honest limits](#honest-limits) is a separate axis and moves independently of
> anything Cloudflare publishes in a blog post.

```
pipx install vibatchium             # core: browse / extract / screenshot / N parallel sessions
# want the stealth HTTP lanes (vb fetch, vb search), the credential vault, VLM read, or the REST shim?
pipx install 'vibatchium[all]'      # everything; or pick extras: vibatchium[fetch], [secrets], [llm], [rest]
patchright install chrome
vb setup                    # register MCP + an auto-discoverable skill so agents reach for vb (idempotent)
```

Core install covers all browsing. `vb fetch` and `vb search` (the curl_cffi
TLS-fingerprint lane) are the `[fetch]` extra; `vb install` reports which optional lanes are available. On a **uv** venv
(no pip), add an extra with `uv pip install --python <venv>/bin/python curl_cffi`.

> Bleeding edge from `master`: `pipx install 'git+https://github.com/trueoriginlabs/vibatchium#egg=vibatchium[all]'`

## Install as a skill / plugin

`vb setup` wires up the agents on *this* machine. To pull just the agent skill
into any agent [skills.sh](https://skills.sh) supports (Claude Code, Codex,
Cursor, Gemini CLI, Copilot, …), or to install skill + MCP server as one Claude
Code plugin:

```
npx skills add trueoriginlabs/vibatchium                  # skill only, any agent

/plugin marketplace add trueoriginlabs/vibatchium         # Claude Code: skill + `vb mcp`
/plugin install vibatchium@vibatchium
```

Both still need the `vb` CLI on `PATH` (`pipx install 'vibatchium[all]'`) — the
skill drives it and the plugin's MCP server *is* `vb mcp`. On Claude Code, pick
the plugin **or** `vb setup`, not both, or you register the server twice. The
skill file is generated from `vibatchium/setup_cmd.py`; edit there and run
`python scripts/sync_skill.py`.

> **Coding agents (Codex / Cursor / Claude Code):** read [`AGENTS.md`](AGENTS.md) first — it has the one-call recipes (`explore`, `research`) and the env-discovery traps to skip.

```
vb explore https://example.com                      # one-call: text-first (screenshot only as a fallback)
vb research --target https://example.com \          # parallel fan-out, N intents
  --intent "pricing model" --intent "customers" --intent "tech stack"
```

**Status:** active development, alpha. **1,807 tests** green in CI (Linux, Python 3.11–3.14). Apache-2.0 (AGPL only via the opt-in `nodriver` extra).

<sub>Detector scores quoted below (bot.sannysoft, CreepJS, Cloudflare cold-launch) are **manual observations, not CI-asserted** — no test in the suite gates on them, and they are only as current as the last hand-run. The generated block under [Measured scores](#measured-scores) is the one to trust; it is empty until someone runs it.</sub>

## Updating

```bash
vb update                  # upgrade + bounce the daemon + refresh the agent skill
vb update --version 0.19.0   # or pin a specific version
```

`vb update` detects how vibatchium was installed (pipx, `uv tool install`,
a pip-less uv venv, or pip with a PEP-668 `--break-system-packages` fallback),
**stops the running daemon** so the next command loads the new code, and
**rewrites the agent skill / docs blocks** so a coding agent is actually told
about the verbs the new version ships (`--no-restart` / `--no-setup` opt out).
Manual equivalent:

```bash
pipx upgrade vibatchium    # or: uv tool upgrade vibatchium / pip install -U vibatchium
vb shutdown                # bounce the daemon — it serves old code until you do
vb setup                   # refresh the agent skill + docs
vb --version               # confirm
```

> The daemon-restart step is the one people miss: the long-running daemon keeps
> serving the **old** version until it's bounced. `vb update` does it for you;
> if you upgrade by hand, run `vb shutdown` (the next `vb` call auto-respawns the
> new version). Optional features upgrade via `pipx install 'vibatchium[all]' --force`.

### Running from a git checkout

`git pull` updates the **source**; whether it updates what `vb` actually runs
depends on the install, and two of the three ways it can fail are silent:

```bash
vb --version && git describe --tags   # do they agree? if not, the install COPIED
                                      # the source — reinstall editable:
                                      #   uv pip install -e '.[all]'
vb status                             # warns when the daemon predates the source
                                      # ("stale_code") — bounce with `vb shutdown`
```

A version-string compare cannot catch a checkout: `git pull` changes the code
without changing `__version__`. `vb status` compares the daemon's boot time
against the newest source file instead, and `vb update` bounces the daemon only
when it is provably behind — so it never drops live sessions for nothing.

### New cap buckets need a re-register

The MCP server's `--caps` list is frozen into your agent's config at first
registration, so a bucket added by a later release (0.19.0 added `search`) stays
invisible no matter how many times you upgrade. Re-running `vb setup` reports
the drift but deliberately won't overwrite a `--caps` you set by hand:

```bash
vb setup                              # reports any cap drift, changes nothing
vb setup --force --caps lean,search   # apply it — exposes `vb search` as a tool
```

Restart the agent session afterwards: the MCP tool list is read once, at start.

## Why vibatchium

Persistent logged-in profiles, credential vaults, CDP-attach, N named sessions —
[agent-browser][ab] and [playwright-mcp][pmcp] all ship those now, at download
volumes we won't match. A comparison table winning rows nobody contests was
noise; it's gone.

What's still ours: **stealth patches in core** (agent-browser's stealth issue has
been open since Jan 2026 and the PR attempting it was closed), **prompt-injection
scanning on by default** for page content (nobody else in this lane ships it —
though it does not yet cover the `fetch`/`search` lanes), **TOTP + IMAP 2FA**
so an unattended run survives a login challenge, and the combination that only
matters together — real stock Chrome + CDP stealth + headless + *unattended* + N
persistent logins, on your own machine.

If you don't need the stealth half, use one of the above. They're bigger, older
and better tested than we are.

[ab]: https://github.com/vercel-labs/agent-browser
[pmcp]: https://github.com/microsoft/playwright-mcp

## Real Chrome vs fake Chrome

A wave of "headless browser for AI agents" tools rebuild the browser from scratch
(Rust + V8, no Blink/Skia) to hit tiny memory and sub-100ms page loads. The catch
is structural: **with no rendering engine, they can't produce a real device's
fingerprint — they synthesize one.** And synthetic fingerprints don't hold still.

vibatchium drives *real* Google Chrome, so its fingerprints are real — and, more
to the point, **stable**. The single test that separates the two is fingerprint
stability across navigations. Run the same canvas + WebGL probe on two pages in
one session:

| | vibatchium (real Chrome) | synthesized-fingerprint engines |
|---|---|---|
| canvas hash, page A → page B | **identical** | reseeded per navigation |
| WebGL `readPixels` | real, **deterministic** pixels | often `Math.random()` |
| WebGL renderer | a real ANGLE renderer¹ | stub / zeros |

<sub>¹ Chrome's own software renderer (SwiftShader) by default — still a coherent, deterministic Chrome value, not a stub. A hardware-GPU string (e.g. `ANGLE (Intel …)`) needs the opt-in `--gpu` flag.</sub>

A real device returns the same fingerprint every page load; a fingerprint keyed
off `Date.now()` does not — and *that inconsistency* is exactly what lie-detection
fingerprinters (CreepJS and friends) flag. Measured: vibatchium's canvas hash and
WebGL readback are byte-identical across