bsession

bsession

Headed browser automation for Claude Code skills. A visible Chromium runs inside a Docker container, and a bsession CLI exposes browser primitives (nav, find, click, fill, extract, …) that your skills chain together. Built for sites that defeat headless scraping — Cloudflare Turnstile, CAPTCHAs, JS-heavy SPAs, anything that needs persistent login cookies or a human handoff via VNC.

bsession ships as a skill itself — once installed, Claude reads its SKILL.md and can scaffold new browser-automation skills on demand.

When to use it

• Site has Cloudflare Turnstile, hCaptcha, or similar bot detection
• A step needs human input at runtime (CAPTCHA, 2FA) — you want to hand off to VNC and resume automatically
• You need persistent login cookies that survive across runs
• The target is a JS-heavy SPA where headless detection bites

Don't use it for sites with a public API, plain HTML, or anything you can scrape with requests + bs4 or playwright headless — those are faster and lighter.

Setup

Prerequisites

• Docker
• Claude Code

One-line install

curl -fsSL https://raw.githubusercontent.com/gaxxx/bsession/main/install.sh | bash

Options:

curl -fsSL .../install.sh | bash -s -- --vnc-password secret
curl -fsSL .../install.sh | bash -s -- --workspace ~/work/bsession

The installer:

1. Clones the repo to ~/.bsession/source/ (re-running updates via git pull)
2. Creates .env from .env.example if missing (all values optional)
3. Pulls the prebuilt multi-arch image ghcr.io/gaxxx/bsession:latest (built in CI for linux/amd64 + linux/arm64) and starts the container (Chromium + agent-browser + VNC + noVNC) — no local build. Falls back to docker compose build only if the pull fails (offline / private registry).
4. Symlinks bsession to ~/.local/bin/bsession
5. Symlinks the bsession skill to ~/.claude/skills/bsession/ so Claude Code can invoke it from any project

Manual install

git clone https://github.com/gaxxx/bsession.git ~/playground/bsession
cd ~/playground/bsession
bash .claude/skills/bsession/scripts/install.sh

As a Claude Code plugin

bsession is also a Claude Code plugin — enable it and the bsession command + skill load automatically in any Claude Code session (interactive or headless claude -p), with no symlinking. The plugin's shim drives the container over its HTTP API, so the engine still needs to be running (see One-line install above; a SessionStart hook reminds you if it isn't).

claude plugin marketplace add gaxxx/bsession
claude plugin install bsession@bsession-marketplace

Or declare it per-project in .claude/settings.json (auto-loads each session, no install step):

{
  "extraKnownMarketplaces": {
    "bsession-marketplace": { "source": { "source": "github", "repo": "gaxxx/bsession" } }
  },
  "enabledPlugins": { "bsession@bsession-marketplace": true }
}

The shim talks to $BSESSION_API_URL (default http://host.docker.internal:18000). This is how another container (e.g. a Telegram assistant) drives bsession over the network without a Docker socket — see docs/superpowers/specs/2026-06-09-persona-bsession-integration-design.md.

Uninstall

bash ~/.bsession/source/.claude/skills/bsession/scripts/install.sh --uninstall

(Stops the container, removes bsession from PATH, removes the skill symlink. Workspace data is preserved.)

Native mode (opt-in)

Docker is the default — it gives you reproducible Linux Chromium and the same VNC handoff path on any machine. But on a personal Mac, running the host's real Chrome gives a stronger fingerprint (Akamai, deeply-fingerprinting sites pass more easily) and skips the Docker exec round-trip.

Set BSESSION_LOCAL=1 to switch:

BSESSION_LOCAL=1 bsession nav https://www.costco.com
BSESSION_LOCAL=1 bsession session list

State lives at ~/.bsession/state/ (separate from the Docker workspace). Same primitives, same skill conventions.

Requirements:

• agent-browser on PATH: npm install -g agent-browser
• Google Chrome installed at the standard macOS path (or set CHROME_BIN)

When to use it: Costco / Akamai / heavy fingerprinting sites where Docker mode struggles, or when you just want to see the browser on your desktop instead of via VNC. For OpenClaw integration or shared/server-side runs, stick with Docker.

OpenClaw integration

If ~/.openclaw/workspace/skills/ exists, the installer also symlinks the skill into ~/.openclaw/workspace/skills/bsession/ so OpenClaw can invoke it.

To run bsession alongside the OpenClaw gateway, use the OpenClaw compose file (mounts ~/.openclaw/workspace/bsession instead of ~/.bsession/workspace):